Skip to main content
Pinecone Docs

Search documentation

Type to search this documentation.

On this pageOverview

Search with a vector

The query operation searches a namespace, using a query vector. It retrieves the ids of the most similar items in a namespace, along with their similarity scores.

For guidance, examples, and limits, see Search.

Python
# pip install "pinecone[grpc]"
from pinecone.grpc import PineconeGRPC as Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")
index = pc.Index("docs-example")

index.query(
    namespace="example-namespace",
    vector=[0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3],
    filter={
        "genre": {"$eq": "documentary"}
    },
    top_k=3,
    include_values=True
)
JavaScript
// npm install @pinecone-database/pinecone
import { Pinecone } from '@pinecone-database/pinecone'

const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' })
const index = pc.index("pinecone-index")

const queryResponse = await index.namespace('example-namespace').query({
    vector: [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3],
    filter: {
      'genre': {'$eq': 'documentary'}
    },
    topK: 3,
    includeValues: true
});
Java
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import io.pinecone.clients.Index;
import io.pinecone.clients.Pinecone;
import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices;

import java.util.Arrays;
import java.util.List;

public class QueryByMetadataExample {
    public static void main(String[] args) {
        Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build();
        Index index = pc.getIndexConnection("pinecone-index");
        List<Float> query = Arrays.asList(0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f);
        Struct filter = Struct.newBuilder()
                .putFields("genre", Value.newBuilder()
                        .setStructValue(Struct.newBuilder()
                                .putFields("$eq", Value.newBuilder()
                                        .setStringValue("documentary")
                                        .build()))
                        .build())
                .build();

        QueryResponseWithUnsignedIndices queryResponse = index.query(3, query, null, null, null, "example-namespace", filter, false, true);

        System.out.println(queryResponse);
    }
}
curl
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"

curl "https://$INDEX_HOST/query" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Pinecone-Api-Version: 2024-04" \
  -d '{
    "vector": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3],
    "filter": {"genre": {"$eq": "documentary"}},
    "topK": 3,
    "includeValues": true
  }'
curl
{
  "matches":[
    {
      "id": "vec3",
      "score": 0,
      "values": [0.3,0.3,0.3,0.3,0.3,0.3,0.3,0.3]
    },
    {
      "id": "vec2",
      "score": 0.0800000429,
      "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]
    },
    {
      "id": "vec4",
      "score": 0.0799999237,
      "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]
    }
  ],
  "namespace": "example-namespace",
  "usage": {"read_units": 6}
}

POST /query

  • namespace (body, string) — The namespace to query.
  • topK (body, integer, required) — The number of results to return for each query.
  • filter (body, object) — The filter to apply. You can use vector metadata to limit your search. See Understanding metadata.
  • includeValues (body, boolean) — Indicates whether vector values are included in the response. For on-demand indexes, setting this to true may increase latency, especially with higher topK values, because vector values are retrieved from object storage. Unless you need vector values, set this to false for better performance.
  • includeMetadata (body, boolean) — Indicates whether metadata is included in the response as well as the ids.
  • queries (body, object[]) — DEPRECATED. Use vector or id instead.
  • vector (body, number[]) — The query vector. This should be the same length as the dimension of the index being queried. Each query() request can contain only one of the parameters id or vector.
  • sparseVector (body, object) — Vector sparse data. Represented as a list of indices and a list of corresponded values, which must be with the same length.
  • id (body, string) — The unique ID of the vector to be used as a query vector. Each request can contain either the vector or id parameter.
  • 200 — A successful response.
  • default — An unexpected error response.
Suggest an edit

Propose a replacement for this page. The site team reviews it before applying any changes.

Export
Documentation menu