Query data

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

The Query operation searches the index, using one or more query vectors. It retrieves the ids of the most similar vectors in the index, 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.

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
Copy
Copied
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': ''}]}
Copy
Copied
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 '{
    "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": ""
#     }
#   ]
# }

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 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.

pythoncurl
Copy
Copied
index.query(
    queries=[([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
)
Copy
Copied
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 '{
    "queries": [
      {"values": [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 topk>1000. This means queries with topk over 1000 should not contain: include_metadata=True or include_data=True. For more limitations, see: Limits.