Query data

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

The Query operation searches a namespace, using one or more query vectors. It retrieves the ids of the most similar vectors in a namespace, along with their similarity scores. It can optionally include the 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.

Learn more

Our Learn section explains the basics of vector databases and similarity search as a service.

Sending a query

You can send multiple queries, and retrieve the top-k most similar vectors for each query. For example, this sends two query vectors and retrieves three matching vectors for each:

pythoncurl
index.query(
  queries=[
    [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3],
    [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]
  ],
  top_k=3,
  include_values=True
)

# Returns:
# {'results': [{'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': ''},
#              {'matches': [{'id': 'D',
#                            'score': 2.14875229e-07,
#                            'values': [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]},
#                           {'id': 'C',
#                            'score': 0.0799998939,
#                            'values': [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]},
#                           {'id': 'E',
#                            'score': 0.0800002143,
#                            'values': [0.49999997, 0.49999997, 0.49999997, 0.49999997, 0.49999997, 0.49999997, 0.49999997, 0.49999997]}],
#               'namespace': ''}]}
curl -i -X POST https://hello-pinecone-YOUR_PROJECT.svc.us-west1-gcp.pinecone.io/query \
  -H 'Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "queries": [
      {"values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]},
      {"values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]}
    ],
    "topK": 3,
    "includeValues": true
  }'

# Output:
# {
#   "results":[
#     {
#       "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": ""
#     }
#     {
#       "matches":[
#         {
#           "id": "D",
#           "score": 0.0800001323,
#           "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]
#         },
#         {
#           "id": "C",
#           "score": -1.76717265e-07,
#           "values": [0.3,0.3,0.3,0.3,0.3,0.3,0.3,0.3]
#         },
#         {
#           "id": "E",
#           "score": 0.0800002143,
#           "values": [0.49999997, 0.49999997, 0.49999997, 0.49999997, 0.49999997, 0.49999997, 0.49999997, 0.49999997]
#         },
#       ],
#       "namespace": ""
#     }
#   ]
# }
note

Depending on your data and your query, you may not get topk results. This happens when topk 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 a small set of partitions, or "namespaces", in order 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.

Query limits

warning

Avoid returning vector data and metadata when top_k>1000.

This means queries with topk over 1000 should not contain: `includemetadata=Trueorinclude_data=True`

We are working on increasing this limit.