# 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"],
)
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
}'
{
"matches": [
{
"_id": "doc-1",
"_score": 0.9281134605407715,
"title": "Introduction to Machine Learning"
}
],
"namespace": "my-namespace",
"usage": {
"read_units": 5
}
}{
"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
}"Unauthorized"{
"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
}{
"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
}Documents
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.
POST
/
namespaces
/
{namespace}
/
documents
/
search
# 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"],
)
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
}'
{
"matches": [
{
"_id": "doc-1",
"_score": 0.9281134605407715,
"title": "Introduction to Machine Learning"
}
],
"namespace": "my-namespace",
"usage": {
"read_units": 5
}
}{
"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
}"Unauthorized"{
"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
}{
"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
}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 infields; naming several scores the query against all of them. Multi-word queries use OR-style matching (case-insensitive). For exact-phrase ranking, usequery_stringwith 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. Does not accept afieldorfieldsparameter. Target specific fields using Lucene field qualifiers in the query string itself:fieldname:valueortitle:(alpha) OR body:(beta).type: "dense_vector", dense vector similarity ranking against adense_vectorfield.type: "sparse_vector", sparse vector similarity ranking against asparse_vectorfield.
$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, update, and delete, 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.# 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"],
)
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
}'
Authorizations
Headers
Required date-based version header
Path Parameters
The namespace to search.
Body
application/json
The request for the search_documents operation.
score_by
Single scoring clause · Dense vector scoring · object · Dense vector scoring · object · Sparse vector scoring · object · Sparse vector scoring · object · Text scoring · object · Text scoring · object · Query string scoring · object[]Multiple text scoring clauses · Dense vector scoring · object · Dense vector scoring · object · Sparse vector scoring · object · Sparse vector scoring · object · Text scoring · object · Text scoring · object · Query string scoring · object[]
required
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.
Required array length:
1 elementA 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 eitherfieldorfieldsnaming exactly one field, and avaluesarray.sparse_vector: Score by sparse vector similarity. Requires eitherfieldorfieldsnaming exactly one field, andsparse_values.text: Score by BM25 text similarity. Requires eitherfieldorfieldsnaming one or more fields, andquery. 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 iffieldorfieldsis provided.
- Dense vector scoring
- Dense vector scoring
- Sparse vector scoring
- Sparse vector scoring
- Text scoring
- Text scoring
- Query string scoring
Show child attributes
Show child attributes
Example:
{
"fields": ["content"],
"query": "What is machine learning?",
"type": "text"
}
The number of top-ranked documents to return.
Required range:
1 <= x <= 10000Example:
10
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.
Example:
["title", "content"]
A metadata filter expression to restrict the documents searched.
Response
A successful search response.
The response for the search_documents operation.
The matching documents, ordered from most to least similar.
Show child attributes
Show child attributes
The namespace that was searched.
Example:
"my-namespace"
Usage information for the search_documents operation.
Show child attributes
Show child attributes
Example:
{ "read_units": 5 }
Was this page helpful?