> ## 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
> Search 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")
# To get the unique host for an index,
# see https://docs.pinecone.io/guides/manage-data/target-an-index
index = pc.Index(host="INDEX_HOST")
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' })
// To get the unique host for an index,
// see https://docs.pinecone.io/guides/manage-data/target-an-index
const index = pc.index("INDEX_NAME", "INDEX_HOST")
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.configs.PineconeConfig;
import io.pinecone.configs.PineconeConnection;
import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices;
import java.util.Arrays;
import java.util.List;
public class QueryExample {
public static void main(String[] args) {
PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
// To get the unique host for an index,
// see https://docs.pinecone.io/guides/manage-data/target-an-index
config.setHost("INDEX_HOST");
PineconeConnection connection = new PineconeConnection(config);
Index index = new Index(connection, "INDEX_NAME");
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);
}
}
```
```go Go theme={null}
package main
import (
"context"
"encoding/json"
"fmt"
"log"
"github.com/pinecone-io/go-pinecone/v4/pinecone"
"google.golang.org/protobuf/types/known/structpb"
)
func prettifyStruct(obj interface{}) string {
bytes, _ := json.MarshalIndent(obj, "", " ")
return string(bytes)
}
func main() {
ctx := context.Background()
pc, err := pinecone.NewClient(pinecone.NewClientParams{
ApiKey: "YOUR_API_KEY",
})
if err != nil {
log.Fatalf("Failed to create Client: %v", err)
}
// To get the unique host for an index,
// see https://docs.pinecone.io/guides/manage-data/target-an-index
idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"})
if err != nil {
log.Fatalf("Failed to create IndexConnection for Host: %v", err)
}
queryVector := []float32{0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3}
metadataMap := map[string]interface{}{
"genre": map[string]interface{}{
"$eq": "documentary",
},
}
metadataFilter, err := structpb.NewStruct(metadataMap)
if err != nil {
log.Fatalf("Failed to create metadata map: %v", err)
}
res, err := idxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{
Vector: queryVector,
TopK: 3,
MetadataFilter: metadataFilter,
IncludeValues: true,
})
if err != nil {
log.Fatalf("Error encountered when querying by vector: %v", err)
} else {
fmt.Printf(prettifyStruct(res))
}
}
```
```csharp C# theme={null}
using Pinecone;
var pinecone = new PineconeClient("YOUR_API_KEY");
// To get the unique host for an index,
// see https://docs.pinecone.io/guides/manage-data/target-an-index
var index = pinecone.Index(host: "INDEX_HOST");
var queryResponse = await index.QueryAsync(new QueryRequest {
Vector = new[] { 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f },
Namespace = "example-namespace",
TopK = 3,
Filter = new Metadata
{
["genre"] =
new Metadata
{
["$eq"] = "documentary",
}
}
});
Console.WriteLine(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: 2025-04" \
-d '{
"namespace": "example-namespace",
"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/2025-04/db_data_2025-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.
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
version: 2025-04
servers:
- url: https://{index_host}
variables:
index_host:
default: unknown
description: host of the index
security:
- ApiKeyAuth: []
tags:
- name: Vector Operations
- name: Bulk Operations
- name: Namespace Operations
externalDocs:
description: More Pinecone.io API docs
url: https://docs.pinecone.io/introduction
paths:
/query:
post:
tags:
- Vector Operations
summary: Search with a vector
description: >-
Search 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: queryVectors
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'
'400':
description: Bad request. The request body included invalid request parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
4XX:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
5XX:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
components:
schemas:
QueryRequest:
description: The request for the `query` operation.
type: object
properties:
namespace:
example: example-namespace
description: The namespace to query.
type: string
topK:
example: 10
description: The number of results to return for each query.
type: integer
minimum: 1
maximum: 10000
required:
- top_k
format: int64
filter:
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).
type: object
includeValues:
example: true
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.
default: 'false'
type: boolean
includeMetadata:
example: true
description: >-
Indicates whether metadata is included in the response as well as
the ids.
default: 'false'
type: boolean
queries:
deprecated: true
description: DEPRECATED. Use `vector` or `id` instead.
type: array
items:
$ref: '#/components/schemas/QueryVector'
minLength: 1
maxLength: 10
vector:
example:
- 0.1
- 0.2
- 0.3
- 0.4
- 0.5
- 0.6
- 0.7
- 0.8
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`.
type: array
items:
type: number
format: float
minLength: 1
maxLength: 20000
sparseVector:
$ref: '#/components/schemas/SparseValues'
id:
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.
type: string
maxLength: 512
required:
- topK
QueryResponse:
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.
type: object
properties:
results:
deprecated: true
description: >-
DEPRECATED. The results of each query. The order is the same as
`QueryRequest.queries`.
type: array
items:
$ref: '#/components/schemas/SingleQueryResults'
matches:
description: The matches for the vectors.
type: array
items:
$ref: '#/components/schemas/ScoredVector'
namespace:
description: The namespace for the vectors.
type: string
usage:
$ref: '#/components/schemas/Usage'
rpcStatus:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
details:
type: array
items:
$ref: '#/components/schemas/protobufAny'
QueryVector:
deprecated: true
description: A single query vector within a `QueryRequest`.
type: object
properties:
values:
example:
- 0.1
- 0.2
- 0.3
- 0.4
- 0.5
- 0.6
- 0.7
- 0.8
description: >-
The query vector values. This should be the same length as the
dimension of the index being queried.
type: array
required:
- values
items:
type: number
format: float
minLength: 1
maxLength: 20000
sparseValues:
$ref: '#/components/schemas/SparseValues'
topK:
example: 10
description: >-
An override for the number of results to return for this query
vector.
type: integer
format: int64
minimum: 1
maximum: 10000
namespace:
example: example-namespace
description: An override the namespace to search.
type: string
filter:
example:
genre:
$in:
- comedy
- documentary
- drama
year:
$eq: 2019
description: >-
An override for the metadata filter to apply. This replaces the
request-level filter.
type: object
required:
- values
SparseValues:
description: >-
Vector sparse data. Represented as a list of indices and a list of
corresponded values, which must be with the same length.
type: object
properties:
indices:
example:
- 1
- 312
- 822
- 14
- 980
description: The indices of the sparse data.
type: array
required:
- indices
items:
type: integer
format: int64
minLength: 1
maxLength: 1000
values:
example:
- 0.1
- 0.2
- 0.3
- 0.4
- 0.5
description: >-
The corresponding values of the sparse data, which must be with the
same length as the indices.
type: array
required:
- values
items:
type: number
format: float
minLength: 1
maxLength: 1000
required:
- indices
- values
SingleQueryResults:
title: The query results for a single `QueryVector`
type: object
properties:
matches:
description: The matches for the vectors.
type: array
items:
$ref: '#/components/schemas/ScoredVector'
namespace:
example: example-namespace
description: The namespace for the vectors.
type: string
ScoredVector:
type: object
properties:
id:
example: example-vector-1
description: This is the vector's unique id.
type: string
required:
- id
minLength: 1
maxLength: 512
score:
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.
type: number
format: float
values:
example:
- 0.1
- 0.2
- 0.3
- 0.4
- 0.5
- 0.6
- 0.7
- 0.8
description: This is the vector data, if it is requested.
type: array
items:
type: number
format: float
sparseValues:
$ref: '#/components/schemas/SparseValues'
metadata:
example:
genre: documentary
year: 2019
description: This is the metadata, if it is requested.
type: object
required:
- id
Usage:
type: object
properties:
readUnits:
example: 5
description: The number of read units consumed by this operation.
type: integer
format: int64
protobufAny:
type: object
properties:
typeUrl:
type: string
value:
type: string
format: byte
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Api-Key
description: >-
An API Key is required to call Pinecone APIs. Get yours from the
[console](https://app.pinecone.io/).
````