Query data

After your data is indexed, you can start sending queries to Pinecone.

The query operation searches the index using a query vector. It retrieves the IDs of the most similar records in the index, along with their similarity scores. This operation can optionally return the result’s vector values and metadata, too. You specify the number of vectors to retrieve each time you send a query. Matches are always ordered by similarity from most similar to least similar.

The similarity score for a vector represents its distance to the query vector, calculated according to the distance metric for the index. The significance of the score depends on the similarity metric. For example, for indexes using the euclidean distance metric, scores with lower values are more similar, while for indexes using the dotproduct metric, higher scores are more similar.

Sending a query

When you send a query, you provide vector values representing your query embedding and a top_k parameter indicating the number of results to return.

For optimal performance, when querying pod-based indexes with top_k over 1000, avoid returning vector data (include_values=True) or metadata (include_metadata=True).

Example

This example sends a query vector and retrieves three matching vectors:

Depending on your data and your query, you may get fewer than top_k results. This happens when top_k is larger than the number of possible matching vectors for your query.

Querying by namespace

You can organize the records added to an index into partitions, or “namespaces,” to limit queries and other vector operations to only one such namespace at a time. For more information, see Namespaces.

Using metadata filters in queries

You can add metadata to document embeddings within Pinecone, and then filter for those criteria when sending the query. Pinecone searches for similar vector embeddings only among those items that match the filter. For more information, see Metadata Filtering.

Querying vectors with sparse and dense values

When querying an index containing sparse and dense vectors, include a sparse_vector in your query parameters.

This feature is in public preview. Consider the current limitations and considerations for serverless indexes, and test thoroughly before using it in production.

Examples

The following example shows how to query with a sparse-dense vector.

To learn more, see Querying sparse-dense vectors.

Data freshness

Pinecone is eventually consistent, so there can be a slight delay before new or changed records are visible to queries. You can use the describe_index_stats operation to check data freshness.