> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinecone.io/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](https://docs.pinecone.io/guides/search/search-overview).
```python Python theme={null}
# 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 JavaScript theme={null}
// 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 Java theme={null}
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 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);
}
}
```
```shell curl theme={null}
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
}'
```
```json curl theme={null}
{
"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}
}
```
## OpenAPI
````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2024-04/data_2024-04.oas.yaml post /query
openapi: 3.0.3
info:
title: Pinecone Data Plane API
description: >-
Pinecone is a vector database that makes it easy to search and retrieve
billions of high-dimensional vectors.
version: 2024-04
contact:
name: Pinecone Support
url: https://support.pinecone.io
email: support@pinecone.io
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://{index_host}
variables:
index_host:
default: unknown
description: host of the index
security:
- ApiKeyAuth: []
tags:
- name: Data Plane
externalDocs:
description: More Pinecone.io API docs
url: https://docs.pinecone.io/introduction
paths:
/query:
post:
tags:
- Data Plane
summary: Search with a vector
description: >-
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](https://docs.pinecone.io/guides/search/search-overview).
operationId: query
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/QueryRequest'
required: true
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
components:
schemas:
QueryRequest:
type: object
properties:
namespace:
type: string
example: example-namespace
description: The namespace to query.
topK:
type: integer
format: int64
example: 10
description: The number of results to return for each query.
maximum: 10000
minimum: 1
required:
- top_k
filter:
type: object
example:
genre:
$in:
- comedy
- documentary
- drama
year:
$eq: 2019
description: >-
The filter to apply. You can use vector metadata to limit your
search. See [Understanding
metadata](https://docs.pinecone.io/guides/index-data/indexing-overview#metadata).
includeValues:
type: boolean
example: true
default: 'false'
description: >-
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:
type: boolean
example: true
default: 'false'
description: >-
Indicates whether metadata is included in the response as well as
the ids.
queries:
type: array
items:
$ref: '#/components/schemas/QueryVector'
description: DEPRECATED. Use `vector` or `id` instead.
maxLength: 10
minLength: 1
deprecated: true
vector:
type: array
example:
- 0.1
- 0.2
- 0.3
- 0.4
- 0.5
- 0.6
- 0.7
- 0.8
items:
type: number
format: float
description: >-
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`.
maxLength: 20000
minLength: 1
sparseVector:
$ref: '#/components/schemas/SparseValues'
id:
type: string
example: example-vector-1
description: >-
The unique ID of the vector to be used as a query vector. Each
request can contain either the `vector` or `id` parameter.
maxLength: 512
description: The request for the `query` operation.
required:
- topK
QueryResponse:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/SingleQueryResults'
description: >-
DEPRECATED. The results of each query. The order is the same as
`QueryRequest.queries`.
deprecated: true
matches:
type: array
items:
$ref: '#/components/schemas/ScoredVector'
description: The matches for the vectors.
namespace:
type: string
description: The namespace for the vectors.
usage:
$ref: '#/components/schemas/Usage'
description: >-
The response for the `query` operation. These are the matches found for
a particular query vector. The matches are ordered from most similar to
least similar.
rpcStatus:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
details:
type: array
items:
$ref: '#/components/schemas/protobufAny'
QueryVector:
type: object
properties:
values:
type: array
example:
- 0.1
- 0.2
- 0.3
- 0.4
- 0.5
- 0.6
- 0.7
- 0.8
items:
type: number
format: float
description: >-
The query vector values. This should be the same length as the
dimension of the index being queried.
maxLength: 20000
minLength: 1
required:
- values
sparseValues:
$ref: '#/components/schemas/SparseValues'
topK:
type: integer
format: int64
example: 10
description: >-
An override for the number of results to return for this query
vector.
maximum: 10000
minimum: 1
namespace:
type: string
example: example-namespace
description: An override the namespace to search.
filter:
type: object
example:
genre:
$in:
- comedy
- documentary
- drama
year:
$eq: 2019
description: >-
An override for the metadata filter to apply. This replaces the
request-level filter.
description: A single query vector within a `QueryRequest`.
required:
- values
deprecated: true
SparseValues:
type: object
description: >-
Vector sparse data. Represented as a list of indices and a list of
corresponded values, which must be with the same length.
properties:
indices:
type: array
description: The indices of the sparse data.
example:
- 1
- 312
- 822
- 14
- 980
items:
type: integer
format: int64
maxLength: 1000
minLength: 1
required:
- indices
values:
type: array
description: >-
The corresponding values of the sparse data, which must be with the
same length as the indices.
example:
- 0.1
- 0.2
- 0.3
- 0.4
- 0.5
items:
type: number
format: float
maxLength: 1000
minLength: 1
required:
- values
required:
- indices
- values
SingleQueryResults:
type: object
properties:
matches:
type: array
items:
$ref: '#/components/schemas/ScoredVector'
description: The matches for the vectors.
namespace:
type: string
example: example-namespace
description: The namespace for the vectors.
title: The query results for a single `QueryVector`
ScoredVector:
type: object
properties:
id:
type: string
example: example-vector-1
description: This is the vector's unique id.
maxLength: 512
minLength: 1
required:
- id
score:
type: number
format: float
example: 0.08
description: >-
This is a measure of similarity between this vector and the query
vector. The higher the score, the more they are similar.
values:
type: array
example:
- 0.1
- 0.2
- 0.3
- 0.4
- 0.5
- 0.6
- 0.7
- 0.8
items:
type: number
format: float
description: This is the vector data, if it is requested.
sparseValues:
$ref: '#/components/schemas/SparseValues'
metadata:
type: object
example:
genre: documentary
year: 2019
description: This is the metadata, if it is requested.
required:
- id
Usage:
type: object
properties:
readUnits:
type: integer
format: int64
example: 5
description: The number of read units consumed by this operation.
protobufAny:
type: object
properties:
typeUrl:
type: string
value:
type: string
format: byte
securitySchemes:
ApiKeyAuth:
type: apiKey
name: Api-Key
description: >-
An API Key is required to call Pinecone APIs. Get yours from the
[console](https://app.pinecone.io/).
in: header
````