Skip to main content
Pinecone Docs
current

Search documentation

Type to search this documentation.

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. 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.

Python
# 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"],
)
curl
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
  }'

POST /namespaces/{namespace}/documents/search

200
{
  "matches": [
    {
      "_id": "doc-1",
      "_score": 0.9281134605407715,
      "title": "Introduction to Machine Learning"
    }
  ],
  "namespace": "my-namespace",
  "usage": {
    "egress_bytes": 1024,
    "read_units": 5
  }
}
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
}
4XX
{
  "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
}
5XX
{
  "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
}

Authorizations

Section titled “Authorizations”
Api-Keystringrequired

An API Key is required to call Pinecone APIs. Get yours from the console.

Headers

Section titled “Headers”
X-Pinecone-Api-Versionstringrequired

Required date-based version header

Typestring
Default2026-07

Path Parameters

Section titled “Path Parameters”
namespacestringrequired

The namespace to search.

Typestring

Body

Section titled “Body”
score_byanyrequired
top_kintegerrequired

The number of top-ranked documents to return.

Required range: 1 <= x <= 10000. Example: 10

Typeinteger
include_fields?string[]

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.

Typestring[]
filter?object

A metadata filter expression to restrict the documents searched.

Typeobject

Response

Section titled “Response”

200 — A successful search response.

The response for the search_documents operation.

matchesobject[]required

The matching documents, ordered from most to least similar.

Typeobject[]
Show child attributes
_idstringrequired

The unique identifier of the matched document.

Required string length: 1+

Typestring
_scorenumber | nullrequired

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.

Typenumber | null
namespacestringrequired

The namespace that served the search: the request's namespace, or the alias's target namespace when the request named a namespace alias.

Example: my-namespace

Typestring
usageobjectrequired

Usage information for the search_documents operation.

Typeobject
Show child attributes
read_unitsintegerrequired

The number of read units consumed by this operation.

Example: 5

Typeinteger
egress_bytes?integer

The billed egress for this response, in bytes. Measured on the encoded response payload.

Required range: 0 <= x. Example: 1024

Typeinteger
Suggest an edit

Propose a replacement for this page. The site team reviews it before applying any changes.

Export
Documentation menu