Search documents

search() ranks the documents in one namespace by the clauses in score_by and returns the top_k best. The examples continue the article-search index from Declare a schema and upsert documents: a dense_vector field body_vector and a sparse_vector field body_sparse_vector, computed from body by your embedding model; full-text title and body fields; and category and year metadata. Searches that have Pinecone embed the query use support-articles, the same kind of index with Pinecone embedding body.

from pinecone import DenseVectorQuery, Pinecone

pc = Pinecone(api_key="your-api-key")
index = pc.index("article-search")

response = index.documents.search(
    namespace="articles-en",
    top_k=10,
    score_by=[DenseVectorQuery(field="body_vector", values=[0.012, -0.087, 0.153])],
    include_fields=["title", "year"],
)
for doc in response.matches:
    print(doc.id, doc.score, doc.title)

Choose a scoring clause

Each clause scores against fields of one kind, so the schema decides which clauses an index can use. The clauses fall into three kinds of search. Semantic and sparse-vector search each come as a pair: one clause takes query text and Pinecone embeds it with the field’s model, the other takes a query vector you computed yourself.

Kind of search

Pass query text

Pass a query vector you computed

Semantic: by meaning

EmbedQuery, on a string field with embed

DenseVectorQuery, on a dense_vector field

Sparse-vector: by weighted term overlap

SparseEmbedQuery, on a string field with sparse_embed

SparseVectorQuery, on a sparse_vector field

Full-text: by the words themselves

TextQuery (BM25 relevance) or QueryStringQuery (a boolean expression), on full-text string fields

score_by also accepts each clause as a plain dict with a type key, such as {"type": "text", "query": "roman aqueduct", "fields": ["title"]}.

Combine clauses

text and query_string clauses can share one score_by list. They are OR’d: a document that matches any clause is returned, and one that matches several scores the sum of its scores. Repeating a clause does not up-weight it; to weight a term, give it a ^N boost inside a QueryStringQuery, such as title:aqueduct^3. To require terms together, use AND inside one QueryStringQuery.

This search matches “roman aqueduct” in title or body, and ranks documents whose title mentions “aqueduct” higher:

from pinecone import QueryStringQuery, TextQuery

response = index.documents.search(
    namespace="articles-en",
    top_k=10,
    score_by=[
        TextQuery(query="roman aqueduct", fields=["title", "body"]),
        QueryStringQuery(query="title:aqueduct^3"),
    ],
)

Currently, a dense_vector, sparse_vector, embed, or sparse_embed clause must be the only clause in score_by. To rank by meaning and keep only documents that contain certain words, add a text-match filter, as in Filter the search. To rank by both meaning and keywords, run one search per clause and merge the results in your code, for example with reciprocal rank fusion.

Choose what comes back

response.matches is ordered best first; an empty list means nothing matched. Each match is a Document: read doc.id and doc.score, then your own fields as attributes.

By default a match carries only its ID and score. Name the fields you will read in include_fields, or pass ["*"] for every stored field. Use doc.get("year") for a field some documents lack, since attribute access raises AttributeError when the field is absent. A string field declared with store_text=False has no stored text to return, and naming it in include_fields fails with a 400.