This page shows you how to search a dense index for records that are most similar in meaning and context to a query. This is often called semantic search, nearest neighbor search, similarity search, or just vector search.

Semantic search uses dense vectors. Each number in a dense vector corresponds to a point in a multidimensional space. Vectors that are closer together in that space are semantically similar.

​
Search with text

Searching with text is supported only for indexes with integrated embedding.

To search a dense index with a query text, use the search_records operation with the following parameters:

  • The namespace to query. To use the default namespace, set the namespace to "__default__".
  • The query.inputs.text parameter with the query text. Pinecone uses the embedding model integrated with the index to convert the text to a dense vector automatically.
  • The query.top_k parameter with the number of similar records to return.
  • Optionally, you can specify the fields to return in the response. If not specified, the response will include all fields.

For example, the following code searches for the 2 records most semantically related to a query text:

from pinecone import Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

# To get the unique host for an index, 
# see https://docs.pinecone.io/guides/manage-data/target-an-index
index = pc.Index(host="INDEX_HOST")

results = index.search(
    namespace="example-namespace", 
    query={
        "inputs": {"text": "Disease prevention"}, 
        "top_k": 2
    },
    fields=["category", "chunk_text"]
)

print(results)

The response will look as follows. Each record is returned with a similarity score that represents its distance to the query vector, calculated according to the similarity metric for the index.

{'result': {'hits': [{'_id': 'rec3',
                      '_score': 0.8204272389411926,
                      'fields': {'category': 'immune system',
                                 'chunk_text': 'Rich in vitamin C and other '
                                               'antioxidants, apples '
                                               'contribute to immune health '
                                               'and may reduce the risk of '
                                               'chronic diseases.'}},
                     {'_id': 'rec1',
                      '_score': 0.7931625843048096,
                      'fields': {'category': 'digestive system',
                                 'chunk_text': 'Apples are a great source of '
                                               'dietary fiber, which supports '
                                               'digestion and helps maintain a '
                                               'healthy gut.'}}]},
 'usage': {'embed_total_tokens': 8, 'read_units': 6}}

​
Search with a dense vector

To search a dense index with a dense vector representation of a query, use the query operation with the following parameters:

  • The namespace to query. To use the default namespace, set the namespace to "__default__".
  • The vector parameter with the dense vector values representing your query.
  • The top_k parameter with the number of results to return.
  • Optionally, you can set include_values and/or include_metadata to true to include the vector values and/or metadata of the matching records in the response. However, when querying with top_k over 1000, avoid returning vector data or metadata for optimal performance.

For example, the following code uses a dense vector representation of the query “Disease prevention” to search for the 3 most semantically similar records in the example-namespaces namespace:

from pinecone.grpc import PineconeGRPC as Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

# To get the unique host for an index, 
# see https://docs.pinecone.io/guides/manage-data/target-an-index
index = pc.Index(host="INDEX_HOST")

index.query(
    namespace="example-namespace",
    vector=[0.0236663818359375,-0.032989501953125, ..., -0.01041412353515625,0.0086669921875], 
    top_k=3,
    include_metadata=True,
    include_values=False
)

The response will look as follows. Each record is returned with a similarity score that represents its distance to the query vector, calculated according to the similarity metric for the index.

{'matches': [{'id': 'rec3',
              'metadata': {'category': 'immune system',
                           'chunk_text': 'Rich in vitamin C and other '
                                          'antioxidants, apples contribute to '
                                          'immune health and may reduce the '
                                          'risk of chronic diseases.'},
              'score': 0.82026422,
              'values': []},
             {'id': 'rec1',
              'metadata': {'category': 'digestive system',
                           'chunk_text': 'Apples are a great source of '
                                          'dietary fiber, which supports '
                                          'digestion and helps maintain a '
                                          'healthy gut.'},
              'score': 0.793068111,
              'values': []},
             {'id': 'rec4',
              'metadata': {'category': 'endocrine system',
                           'chunk_text': 'The high fiber content in apples '
                                          'can also help regulate blood sugar '
                                          'levels, making them a favorable '
                                          'snack for people with diabetes.'},
              'score': 0.780169606,
              'values': []}],
 'namespace': 'example-namespace',
 'usage': {'read_units': 6}}

​
Search with a record ID

When you search with a record ID, Pinecone uses the dense vector associated with the record as the query. To search a dense index with a record ID, use the query operation with the following parameters:

  • The namespace to query. To use the default namespace, set the namespace to "__default__".
  • The id parameter with the unique record ID containing the vector to use as the query.
  • The top_k parameter with the number of results to return.
  • Optionally, you can set include_values and/or include_metadata to true to include the vector values and/or metadata of the matching records in the response. However, when querying with top_k over 1000, avoid returning vector data or metadata for optimal performance.

For example, the following code uses an ID to search for the 3 records in the example-namespace namespace that are most semantically similar to the dense vector in the record:

from pinecone.grpc import PineconeGRPC as Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

# To get the unique host for an index, 
# see https://docs.pinecone.io/guides/manage-data/target-an-index
index = pc.Index(host="INDEX_HOST")

index.query(
    namespace="example-namespace",
    id="rec2", 
    top_k=3,
    include_metadata=True,
    include_values=False
)

​
Parallel queries

Python SDK v6.0.0 and later provide async methods for use with asyncio. Async support makes it possible to use Pinecone with modern async web frameworks such as FastAPI, Quart, and Sanic, and can significantly increase the efficiency of running queries in parallel. For more details, see the Async requests.