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': ''}
const index = pinecone.index("example-index");
const queryResponse = await Index.query({
query: {
vector: [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3],
topK: 3,
includeValues: true,
},
namespace: "example-namespace",
});
// 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
)
const index = pinecone.index("example-index")
const queryResponse = await index.query({
query: {
vector: [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1],
topK: 1,
includeMetadata: true
filters: {
"genre": {"$eq": "documentary"}
},
}
})
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
}'
Querying vectors with sparse and dense values
When querying an index containing sparse and dense vectors, use the query()
operation with the sparse_vector
parameter present.
Warning
The
Update
operation does not validate the existence of ids within an
index. If a non-existent id is given then no changes are made and a200 OK
will be returned.
Examples
The following example queries the index example-index with a sparse-dense vector.
query_response = index.query(
namespace="example-namespace",
top_k=10,
vector=[0.1, 0.2, 0.3, 0.4],
sparse_vector={
'indices': [10, 45, 16],
'values': [0.5, 0.5, 0.2]
}
)
curl --request POST \
--url https://index_name-project_id.svc.environment.pinecone.io/query \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"includeValues": "false",
"includeMetadata": "false",
"vector": [
0.1,
0.2,
0.3,
0.4
],
"sparseVector": {
"indices": [
10,
45,
16
],
"values": [
0.5,
0.5,
0.2
]
},
"topK": 10,
"namespace": "example-namespace"
}
'
Limitations
Avoid returning vector data and metadata when top_k
is greater than 1000. This means queries with top_k
over 1000 should not contain include_metadata=True
or include_data=True
. For more limitations, see: Limits.
Updated 20 days ago