> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinecone.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Search documents
> Search for documents in a namespace using one or more scoring methods (dense vector, sparse vector, text, or query string similarity).
Returns the top-k most similar documents along with their scores and requested fields.
A request includes a `score_by` array selecting one of the following scoring types:
* **`type: "text"`**, BM25 token matching over one or more text fields named in `fields`; naming several scores the query against all of them. Multi-word queries use OR-style matching (case-insensitive). For exact-phrase ranking, use `query_string` with quoted terms.
* **`type: "query_string"`**, Lucene query syntax. Supports boolean operators, phrase prefix matching, boosting, fuzzy matching (`term~`, `term~N`), and cross-field queries. See the [query syntax reference](/guides/search/full-text-search/query-syntax). **Does not accept a `field` or `fields` parameter.** Target specific fields using Lucene field qualifiers in the query string itself: `fieldname:value` or `title:(alpha) OR body:(beta)`.
* **`type: "dense_vector"`**, dense vector similarity ranking against a `dense_vector` field.
* **`type: "sparse_vector"`**, sparse vector similarity ranking against a `sparse_vector` field.
Any scoring method can be combined with metadata filters (including text match operators `$match_phrase` / `$match_all` / `$match_any` and logical operators `$and` / `$or` / `$not`). Filters are applied **before** scoring: the search only considers documents that match the filter. Scoring-only operators are available in `query_string` scoring but cannot be used inside `filter`: phrase slop (`"phrase"~N`), term boosting (`^N`), and phrase prefix (`"phrase pre"*`).
`include_fields` defaults to `[]` (returns only `_id` and `_score`); use `["*"]` to return all stored fields.
A single search request ranks by one scoring type. Multi-field BM25 is supported: name several fields in one `text` clause's `fields` array, or pass multiple `text` clauses, which the server combines into one ranking; a `query_string` clause can also target several fields. Every contributing field weighs equally in `2026-07`; there is no per-field weight parameter. To combine BM25 ranking with `dense_vector` or `sparse_vector` ranking, restrict the dense (or sparse) search with a text-match filter (`$match_phrase`, `$match_all`, `$match_any`) on the full-text field, or run separate searches and merge the results client-side.
Text match operators are only valid on this endpoint. Plain metadata filters, however, are also accepted by [fetch](/reference/api/2026-07/data-plane/fetch_documents), [update](/reference/api/2026-07/data-plane/update_documents), and [delete](/reference/api/2026-07/data-plane/delete_documents), so you can fetch, update, or delete documents matching a metadata expression directly. Text match operators (`$match_phrase`, `$match_all`, `$match_any`) stay search-only; to act on their results elsewhere, search first to get IDs.
```python Python theme={null}
# pip install --upgrade pinecone
import os
from pinecone import Pinecone
pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])
index = pc.Index(name="articles")
NAMESPACE = "example-namespace"
# BM25 token matching
response = index.documents.search(
namespace=NAMESPACE,
top_k=10,
score_by=[{"type": "text", "fields": ["body"], "query": "machine learning"}],
include_fields=["title", "body", "category", "year"],
)
for match in response.matches:
print(match._id, match._score, getattr(match, "title", ""))
# Lucene query string
response = index.documents.search(
namespace=NAMESPACE,
top_k=10,
score_by=[{"type": "query_string", "query": "title:(quantum) OR body:(machine learning)"}],
include_fields=["title", "body"],
)
# Dense vector ranking with phrase-match filter
query_vector = [0.12, 0.34, 0.56] # replace with your actual query vector
response = index.documents.search(
namespace=NAMESPACE,
top_k=10,
score_by=[{
"type": "dense_vector",
"fields": ["embedding"],
"values": query_vector,
}],
filter={"body": {"$match_phrase": "machine learning"}},
include_fields=["title", "body"],
)
```
```shell curl theme={null}
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="articles-abc123.svc.us-east-1.pinecone.io"
# EXAMPLE REQUEST 1: BM25 token matching (type: "text")
curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"include_fields": ["title", "body", "category", "year"],
"score_by": [{
"type": "text",
"fields": ["body"],
"query": "machine learning"
}],
"top_k": 10
}'
# EXAMPLE REQUEST 2: Cross-field boolean query (type: "query_string")
curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"include_fields": ["title", "body"],
"score_by": [{
"type": "query_string",
"query": "title:(quantum) OR body:(machine learning)"
}],
"top_k": 10
}'
# EXAMPLE REQUEST 3: Dense vector ranking with phrase-match filter
curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"include_fields": ["title", "body"],
"filter": { "body": { "$match_phrase": "machine learning" } },
"score_by": [{
"type": "dense_vector",
"fields": ["embedding"],
"values": [0.12, 0.34, 0.56]
}],
"top_k": 10
}'
# EXAMPLE REQUEST 4: Sparse vector ranking
curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"include_fields": ["title", "body"],
"score_by": [{
"type": "sparse_vector",
"fields": ["sparse_embedding"],
"sparse_values": {
"indices": [12, 287, 4096],
"values": [0.41, 0.33, 0.18]
}
}],
"top_k": 10
}'
# EXAMPLE REQUEST 5: Compound filter ($and + $match_all + metadata)
curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Pinecone-Api-Version: 2026-07" \
-d '{
"include_fields": ["body", "category", "year"],
"filter": {
"$and": [
{ "body": { "$match_all": "federal reserve" } },
{ "category": { "$eq": "finance" } },
{ "year": { "$gte": 2024 } }
]
},
"score_by": [{
"type": "text",
"fields": ["body"],
"query": "monetary policy impact"
}],
"top_k": 10
}'
```
## OpenAPI
````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.oas.yaml post /namespaces/{namespace}/documents/search
openapi: 3.0.3
info:
title: Pinecone Data Plane API
description: >-
Pinecone is a vector database that makes it easy to search and retrieve
billions of high-dimensional vectors.
contact:
name: Pinecone Support
url: https://support.pinecone.io
email: support@pinecone.io
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
version: 2026-07
servers:
- url: https://{index_host}
variables:
index_host:
default: unknown
description: host of the index
security:
- ApiKeyAuth: []
tags:
- name: Vector Operations
- name: Bulk Operations
- name: Namespace Operations
- name: Document Operations
description: >-
Operations on documents in an index created with a document schema — one
that declares at least one full-text-searchable string field or a
`dense_vector` / `sparse_vector` field under a name other than the
reserved `_values` / `_sparse_values`. Metadata fields alone do not make a
document schema. Indexes served by the vectors API — created from
`dimension`/`metric` on an earlier API version, or from a schema holding
only the reserved vector fields and metadata — and indexes served by the
records API — created with an integrated embedding model, whose schema
holds a single `semantic_text` field — reject every document operation
with `400` and name the API to use instead. A document index accepts only
the document operations; the vector data operations (upsert, query, fetch,
update, delete, list) reject it, while index stats and the namespace
operations remain available.
externalDocs:
description: More Pinecone.io API docs
url: https://docs.pinecone.io/introduction
paths:
/namespaces/{namespace}/documents/search:
post:
tags:
- Document Operations
summary: Search documents
description: >-
Search for documents in a namespace using one or more scoring methods
(dense vector, sparse vector, text, or query string similarity).
Returns the top-k most similar documents along with their scores and
requested fields.
operationId: searchDocuments
parameters:
- in: header
name: X-Pinecone-Api-Version
description: Required date-based version header
required: true
schema:
default: 2026-07
type: string
style: simple
- in: path
name: namespace
description: The namespace to search.
required: true
schema:
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchDocumentsRequest'
required: true
responses:
'200':
description: A successful search response.
content:
application/json:
schema:
$ref: '#/components/schemas/SearchDocumentsResponse'
links:
FetchMatchedDocument:
description: Look up a document returned as a search match.
operationId: fetchDocuments
parameters:
namespace: $request.path.namespace
'400':
description: Bad request. The request body included invalid request parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: 'Unauthorized. Possible causes: missing or invalid API key.'
content:
text/plain:
schema:
$ref: '#/components/schemas/UnauthorizedMessage'
4XX:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
5XX:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
SearchDocumentsRequest:
example:
include_fields:
- title
- content
score_by:
- fields:
- content
query: What is machine learning?
type: text
top_k: 10
description: The request for the `search_documents` operation.
type: object
properties:
score_by:
description: >-
The list of scoring methods to use for ranking documents.
A single clause of any type is always valid. Several clauses may be
combined only when every one of them is `text` or `query_string`; a
`dense_vector` or `sparse_vector` clause must appear on its own.
type: array
items:
$ref: '#/components/schemas/DocumentScoringMethod'
minItems: 1
maxItems: 100
oneOf:
- title: Single scoring clause
maxItems: 1
- title: Multiple text scoring clauses
items:
type: object
properties:
type:
description: >-
Multiple scoring clauses must use `text` or
`query_string`.
type: string
enum:
- text
- query_string
minItems: 2
top_k:
example: 10
description: The number of top-ranked documents to return.
type: integer
format: int32
minimum: 1
maximum: 10000
include_fields:
example:
- title
- content
description: >-
The document fields to return on each match alongside `_id` and
`_score`. When omitted or empty, no fields are returned. Pass
`["*"]` to return every field.
type: array
items:
type: string
filter:
description: A metadata filter expression to restrict the documents searched.
type: object
required:
- score_by
- top_k
SearchDocumentsResponse:
example:
matches:
- _id: doc-1
_score: 0.9281134605407715
title: Introduction to Machine Learning
namespace: my-namespace
usage:
read_units: 5
description: The response for the `search_documents` operation.
type: object
properties:
matches:
description: The matching documents, ordered from most to least similar.
type: array
items:
$ref: '#/components/schemas/DocumentSearchMatch'
namespace:
example: my-namespace
description: The namespace that was searched.
type: string
usage:
$ref: '#/components/schemas/DocumentSearchUsage'
required:
- matches
- namespace
- usage
ErrorResponse:
example:
error:
code: INVALID_ARGUMENT
message: >-
No 'ids' or 'filter' provided in the document fetch request. Provide
at least one document ID in 'ids', or a metadata filter in 'filter'.
status: 400
description: >-
The error response shape returned by the records and documents
operations. The vector operations return `rpcStatus` instead. Requests
rejected by the authentication and rate-limiting layer before they reach
the service (`401`, and the `400`, `403`, and `429` it produces) return
a plain-text body on every operation.
type: object
properties:
status:
example: 400
description: The HTTP status code of the error.
type: integer
error:
description: Detailed information about the error that occurred.
type: object
properties:
code:
example: INVALID_ARGUMENT
description: >-
The error code.
Possible values: `OK`, `UNKNOWN`, `INVALID_ARGUMENT`,
`DEADLINE_EXCEEDED`, `NOT_FOUND`, `ALREADY_EXISTS`,
`PERMISSION_DENIED`, `UNAUTHENTICATED`, `RESOURCE_EXHAUSTED`,
`FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `INTERNAL`,
`FORBIDDEN`, `PAYMENT_REQUIRED`, `SERVICE_UNAVAILABLE`, or
`PAYLOAD_TOO_LARGE`.
x-enum:
- OK
- UNKNOWN
- INVALID_ARGUMENT
- DEADLINE_EXCEEDED
- NOT_FOUND
- ALREADY_EXISTS
- PERMISSION_DENIED
- UNAUTHENTICATED
- RESOURCE_EXHAUSTED
- FAILED_PRECONDITION
- ABORTED
- OUT_OF_RANGE
- INTERNAL
- FORBIDDEN
- PAYMENT_REQUIRED
- SERVICE_UNAVAILABLE
- PAYLOAD_TOO_LARGE
type: string
message:
example: >-
No 'ids' or 'filter' provided in the document fetch request.
Provide at least one document ID in 'ids', or a metadata filter
in 'filter'.
description: >-
A human-readable description of the error, including how to
correct the request where possible.
type: string
required:
- code
- message
required:
- status
- error
UnauthorizedMessage:
example: Unauthorized
description: >-
The plain-text body of a `401` response. Authentication failures are
rejected before the request reaches the index, so they carry the message
`Unauthorized` rather than an error object.
type: string
DocumentScoringMethod:
example:
fields:
- content
query: What is machine learning?
type: text
description: >-
A scoring method that defines how documents are scored against a query.
The `type` field determines which other fields are used:
- `dense_vector`: Score by dense vector similarity. Requires either
`field` or `fields` naming exactly one field, and a `values` array.
- `sparse_vector`: Score by sparse vector similarity. Requires either
`field` or `fields` naming exactly one field, and `sparse_values`.
- `text`: Score by BM25 text similarity. Requires either `field` or
`fields` naming one or more fields, and `query`. Naming several fields
scores the query against all of them.
- `query_string`: Score using a Lucene query string. Use field
qualifiers (`field:(clause)`) to target a field, or omit field
qualifiers to search against all text-searchable fields. Errors if
`field` or `fields` is provided.
type: object
properties:
type:
description: >-
The scoring method type.
Possible values: `dense_vector`, `sparse_vector`, `text`, or
`query_string`.
x-enum:
- dense_vector
- sparse_vector
- text
- query_string
type: string
fields:
example:
- content
description: >-
The fields to score against.
Either `fields` or `field` must be provided for `dense_vector`,
`sparse_vector`, and `text` scoring types, and neither may be
provided for `query_string`. `dense_vector` and `sparse_vector`
accept exactly one field; `text` accepts one or more.
type: array
items:
type: string
minItems: 1
field:
deprecated: true
description: >-
A single field to score against. Equivalent to a one-element
`fields`; prefer `fields`, which can also name more than one field.
Either `field` or `fields` must be provided for `dense_vector`,
`sparse_vector`, and `text` scoring types, but not both.
type: string
query:
description: >-
The text query to use for `text` and `query_string` scoring types.
Leading and trailing whitespace is trimmed; a query that is empty
after trimming is rejected. At most 10 KB.
type: string
minLength: 1
values:
description: The dense vector values to use for `dense_vector` scoring type.
type: array
items:
type: number
format: float
sparse_values:
$ref: '#/components/schemas/SparseValues'
required:
- type
anyOf:
- title: Dense vector scoring
properties:
type:
enum:
- dense_vector
fields:
maxItems: 1
required:
- type
- values
anyOf:
- required:
- field
- required:
- fields
- title: Sparse vector scoring
properties:
type:
enum:
- sparse_vector
fields:
maxItems: 1
required:
- type
- sparse_values
anyOf:
- required:
- field
- required:
- fields
- title: Text scoring
properties:
type:
enum:
- text
required:
- type
- query
anyOf:
- required:
- field
- required:
- fields
- title: Query string scoring
properties:
type:
enum:
- query_string
required:
- type
- query
not:
anyOf:
- required:
- field
- required:
- fields
not:
required:
- field
- fields
DocumentSearchMatch:
example:
_id: doc-1
_score: 0.9281134605407715
content: Machine learning is a subset of artificial intelligence.
title: Introduction to Machine Learning
description: >-
A document match returned from a search operation, including the
document ID, similarity score, and selected fields.
type: object
properties:
_id:
description: The unique identifier of the matched document.
type: string
minLength: 1
_score:
nullable: true
description: >-
The similarity score of the matched document. `null` when the score
is not a finite number, which can happen for dense vectors of very
large magnitude.
type: number
format: float
required:
- _id
- _score
additionalProperties: true
DocumentSearchUsage:
example:
read_units: 5
description: Usage information for the `search_documents` operation.
type: object
properties:
read_units:
example: 5
description: The number of read units consumed by this operation.
type: integer
format: int32
required:
- read_units
SparseValues:
description: >-
Vector sparse data. Represented as a list of indices and a list of
corresponded values, which must be with the same length.
type: object
properties:
indices:
example:
- 1
- 312
- 822
- 14
- 980
description: The indices of the sparse data.
type: array
items:
type: integer
format: int64
minimum: 0
maximum: 4294967295
minItems: 1
maxItems: 2048
values:
example:
- 0.1
- 0.2
- 0.3
- 0.4
- 0.5
description: >-
The corresponding values of the sparse data, which must be with the
same length as the indices.
type: array
items:
type: number
format: float
minItems: 1
maxItems: 2048
required:
- indices
- values
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Api-Key
description: >-
An API Key is required to call Pinecone APIs. Get yours from the
[console](https://app.pinecone.io/).
````