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 vectors in the index, along with their similarity scores. It can optionally include the result vectors' values and metadata too. You specify the number of vectors to retrieve each time you send a query. They are always ordered by similarity from most similar to least similar.

Sending a query

When you send a query, you provide a vector and retrieve the top-k most similar vectors for each query. For example, this example sends a query vector and retrieves three matching vectors:

index.query(
  vector=[0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3],
  top_k=3,
  include_values=True
)

# Returns:
# {'matches': [{'id': 'C',
#               'score': -1.76717265e-07,
#               'values': [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]},
#                   {'id': 'B',
#                    'score': 0.080000028,
#                    'values': [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]},
#                   {'id': 'D',
#                    'score': 0.0800001323,
#                    'values': [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]}],
#               'namespace': ''}

curl -i -X POST https://hello-pinecone-YOUR_PROJECT.svc.YOUR_ENVIRONMENT.pinecone.io/query \
  -H 'Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "vector":[0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3],
    "topK": 3,
    "includeValues": true
  }'

# Output:
# {
#  "matches":[
#      {
#       "id": "C",
#       "score": -1.76717265e-07,
#       "values": [0.3,0.3,0.3,0.3,0.3,0.3,0.3,0.3]
#      },
#      {
#       "id": "B",
#       "score": 0.080000028,
#       "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]
#      },
#      {
#       "id": "D",
#       "score": 0.0800001323,
#       "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]
#      }
#  ],
#  "namespace": ""
# }

Depending on your data and your query, you may not get 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 vectors 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 will search for similar vector embeddings only among those items that match the filter. For more information, see: Metadata Filtering.

index.query(
    vector=[0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1],
    filter={
        "genre": {"$eq": "documentary"},
        "year": 2019
    },
    top_k=1,
    include_metadata=True
)

curl -i -X POST https://YOUR_INDEX-YOUR_PROJECT.svc.YOUR_ENVIRONMENT.pinecone.io/query \
  -H 'Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1],
    "filter": {"genre": {"$in": ["comedy", "documentary", "drama"]}},
    "topK": 1,
    "includeMetadata": true
  }'

Limitations

Avoid returning vector data and metadata when top_k>1000. This means queries with top_k over 1000 should not contain: include_metadata=True or include_data=True. For more limitations, see: Limits.