Query data

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

The query endpoint 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 endpoint 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.

​

Query limits

• The max value for top_k, the number of results to return, is 10,000.

• The result size limit for a query is 4MB. The result size is affected by the dimension of the dense vectors and whether or not dense vector values and metadata are included in the result.

  If a query fails due to exceeding the 4MB result size limit, choose a lower top_k value, or use include_metadata=False or include_values=False to exclude metadata or values from the result.

​

Sending a query

Each query must include a query vector, specified by either a vector or id, and the number of results to return, specified by the top_k parameter.

​

Querying by vector

To query by vector, provide the vector values representing your query embedding and the topK parameter.

The following example sends a query vector with vector values 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 record ID

To query by record ID, provide the unique record ID and the topK parameter.

The following example sends a query vector with an id value and retrieves three matching vectors:

For more information, see Limitations of querying by ID.

​

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.

Only indexes using the dotproduct metric support querying sparse vectors.

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 endpoint to check data freshness.