> ## 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 text
> Search a namespace with a query text, query vector, or record ID and return the most similar records, along with their similarity scores. Optionally, rerank the initial results based on their relevance to the query.
Searching with text is supported only for [indexes with integrated embedding](https://docs.pinecone.io/guides/indexes/create-an-index#integrated-embedding). Searching with a query vector or record ID is supported for all indexes.
For guidance, examples, and limits, see [Search](https://docs.pinecone.io/guides/search/search-overview).
```python Python theme={null}
from pinecone import 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("docs-example")
# Search with a query text and rerank the results
# Supported only for indexes with integrated embedding
search_with_text = index.search(
namespace="example-namespace",
query={
"inputs": {"text": "Disease prevention"},
"top_k": 4
},
fields=["category", "chunk_text"],
rerank={
"model": "bge-reranker-v2-m3",
"top_n": 2,
"rank_fields": ["chunk_text"] # Specified field must also be included in 'fields'
}
)
print(search_with_text)
# Search with a query vector and rerank the results
search_with_vector = index.search(
namespace="example-namespace",
query={
"vector": {
"values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]
},
"top_k": 4
},
fields=["category", "chunk_text"],
rerank={
"query": "Disease prevention",
"model": "bge-reranker-v2-m3",
"top_n": 2,
"rank_fields": ["chunk_text"] # Specified field must also be included in 'fields'
}
)
print(search_with_vector)
# Search with a record ID and rerank the results
search_with_id = index.search(
namespace="example-namespace",
query={
"id": "rec1",
"top_k": 4
},
fields=["category", "chunk_text"],
rerank={
"query": "Disease prevention",
"model": "bge-reranker-v2-m3",
"top_n": 2,
"rank_fields": ["chunk_text"] # Specified field must also be included in 'fields'
}
)
print(search_with_id)
```
```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 namespace = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace");
// Search with a query text and rerank the results
// Supported only for indexes with integrated embedding
const searchWithText = await namespace.searchRecords({
query: {
topK: 4,
inputs: { text: 'Disease prevention' },
},
fields: ['chunk_text', 'category'],
rerank: {
model: 'bge-reranker-v2-m3',
rankFields: ['chunk_text'],
topN: 2,
},
});
console.log(searchWithText);
// Search with a query vector and rerank the results
const searchWithVector = await namespace.searchRecords({
query: {
topK: 4,
vector: {
values: [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]
},
inputs: { text: 'Disease prevention' },
},
fields: ['chunk_text', 'category'],
rerank: {
query: "Disease prevention",
model: 'bge-reranker-v2-m3',
rankFields: ['chunk_text'],
topN: 2,
},
});
console.log(searchWithVector);
// Search with a record ID and rerank the results
const searchWithId = await namespace.searchRecords({
query: {
topK: 4,
id: 'rec1',
},
fields: ['chunk_text', 'category'],
rerank: {
query: "Disease prevention",
model: 'bge-reranker-v2-m3',
rankFields: ['chunk_text'],
topN: 2,
},
});
console.log(searchWithId);
```
```java Java theme={null}
import io.pinecone.clients.Index;
import io.pinecone.configs.PineconeConfig;
import io.pinecone.configs.PineconeConnection;
import org.openapitools.db_data.client.ApiException;
import org.openapitools.db_data.client.model.SearchRecordsRequestRerank;
import org.openapitools.db_data.client.model.SearchRecordsResponse;
import org.openapitools.db_data.client.model.SearchRecordsVector;
import java.util.*;
public class SearchText {
public static void main(String[] args) throws ApiException {
PineconeConfig config = new PineconeConfig("YOUR_API_KEY");
config.setHost("INDEX_HOST");
PineconeConnection connection = new PineconeConnection(config);
Index index = new Index(config, connection, "integrated-dense-java");
String query = "Famous historical structures and monuments";
List fields = new ArrayList<>();
fields.add("category");
fields.add("chunk_text");
ListrankFields = new ArrayList<>();
rankFields.add("chunk_text");
SearchRecordsRequestRerank rerank = new SearchRecordsRequestRerank()
.query(query)
.model("bge-reranker-v2-m3")
.topN(2)
.rankFields(rankFields);
// Search with a query text and rerank the results
// Supported only for indexes with integrated embedding
SearchRecordsResponse searchWithText = index.searchRecordsByText(query, "example-namespace", fields, 10, null, rerank);
System.out.println(searchWithText);
// Search with a query vector and rerank the results
SearchRecordsVector queryVector = new SearchRecordsVector();
queryVector.setValues(Arrays.asList(0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f));
SearchRecordsResponse searchWithVector = index.searchRecordsByVector(queryVector, "example-namespace", fields, 4, null, rerank);
System.out.println(searchWithVector);
// Search with a record ID and rerank the results
SearchRecordsResponse searchWithID = index.searchRecordsById("rec1", "example-namespace", fields, 4, null, rerank);
System.out.println(searchWithID);
}
}
```
```go Go theme={null}
package main
import (
"context"
"encoding/json"
"fmt"
"log"
"github.com/pinecone-io/go-pinecone/v4/pinecone"
)
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)
}
// Search with a query text and rerank the results
// Supported only for indexes with integrated embedding
topN := int32(2)
searchWithText, err := idxConnection.SearchRecords(ctx, &pinecone.SearchRecordsRequest{
Query: pinecone.SearchRecordsQuery{
TopK: 4,
Inputs: &map[string]interface{}{
"text": "Disease prevention",
},
},
Rerank: &pinecone.SearchRecordsRerank{
Model: "bge-reranker-v2-m3",
TopN: &topN,
RankFields: []string{"chunk_text"},
},
Fields: &[]string{"chunk_text", "category"},
})
if err != nil {
log.Fatalf("Failed to search records: %v", err)
}
fmt.Printf(prettifyStruct(searchWithText))
// Search with a query vector and rerank the results
topN := int32(2)
searchWithVector, err := idxConnection.SearchRecords(ctx, &pinecone.SearchRecordsRequest{
Query: pinecone.SearchRecordsQuery{
TopK: 4,
Vector: pinecone.SearchRecordsVector{
Values: []float32{0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3},
},
},
Rerank: &pinecone.SearchRecordsRerank{
Model: "bge-reranker-v2-m3",
TopN: &topN,
RankFields: []string{"chunk_text"},
},
Fields: &[]string{"chunk_text", "category"},
})
if err != nil {
log.Fatalf("Failed to search records: %v", err)
}
fmt.Printf(prettifyStruct(resSearchWithVector))
// Search with a query ID and rerank the results
topN := int32(2)
searchWithId, err := idxConnection.SearchRecords(ctx, &pinecone.SearchRecordsRequest{
Query: pinecone.SearchRecordsQuery{
TopK: 4,
Id: "rec1",
},
Rerank: &pinecone.SearchRecordsRerank{
Model: "bge-reranker-v2-m3",
TopN: &topN,
RankFields: []string{"chunk_text"},
},
Fields: &[]string{"chunk_text", "category"},
})
if err != nil {
log.Fatalf("Failed to search records: %v", err)
}
fmt.Printf(prettifyStruct(searchWithId))
}
```
```csharp C# theme={null}
using Pinecone;
var pinecone = new PineconeClient("YOUR_API_KEY");
var index = pinecone.Index(host: "INDEX_HOST");
// Search with a query text and rerank the results
var searchWithText = await index.SearchRecordsAsync(
"example-namespace",
new SearchRecordsRequest
{
Query = new SearchRecordsRequestQuery
{
TopK = 4,
Inputs = new Dictionary { { "text", "Disease prevention" } },
},
Fields = ["category", "chunk_text"],
Rerank = new SearchRecordsRequestRerank
{
Model = "bge-reranker-v2-m3",
TopN = 2,
RankFields = ["chunk_text"],
},
}
);
Console.WriteLine(searchWithText);
// Search with a query vector and rerank the results
var searchWithVector = await index.SearchRecordsAsync(
"example-namespace",
new SearchRecordsRequest
{
Query = new SearchRecordsRequestQuery
{
TopK = 4,
Vector = new SearchRecordsVector
{
Values = new float[] { 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f },
},
},
Fields = ["category", "chunk_text"],
Rerank = new SearchRecordsRequestRerank
{
Model = "bge-reranker-v2-m3",
TopN = 2,
RankFields = ["chunk_text"],
},
}
);
Console.WriteLine(searchWithVector);
// Search with a query ID and rerank the results
var searchWithId = await index.SearchRecordsAsync(
"example-namespace",
new SearchRecordsRequest
{
Query = new SearchRecordsRequestQuery
{
TopK = 4,
Id = "rec1",
},
Fields = ["category", "chunk_text"],
Rerank = new SearchRecordsRequestRerank
{
Model = "bge-reranker-v2-m3",
TopN = 2,
RankFields = ["chunk_text"],
},
}
);
Console.WriteLine(searchWithId);
```
```shell curl theme={null}
INDEX_HOST="INDEX_HOST"
NAMESPACE="YOUR_NAMESPACE"
PINECONE_API_KEY="YOUR_API_KEY"
# Search with a query text and rerank the results
# Supported only for indexes with integrated embedding
curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "X-Pinecone-Api-Version: 2025-04" \
-d '{
"query": {
"inputs": {"text": "Disease prevention"},
"top_k": 4,
},
"fields": ["category", "chunk_text"]
"rerank": {
"model": "bge-reranker-v2-m3",
"top_n": 2,
"rank_fields": ["chunk_text"] # Specified field must also be included in 'fields'
}
}'
# Search with a query vector and rerank the results
curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "X-Pinecone-Api-Version: 2025-04" \
-d '{
"query": {
"vector": {
"values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]
},
"top_k": 4,
},
"fields": ["category", "chunk_text"]
"rerank": {
"query": "Disease prevention",
"model": "bge-reranker-v2-m3",
"top_n": 2,
"rank_fields": ["chunk_text"] # Specified field must also be included in 'fields'
}
}'
# Search with a record ID and rerank the results
# Supported only for indexes with integrated embedding
curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "X-Pinecone-Api-Version: 2025-04" \
-d '{
"query": {
"id": "rec1",
"top_k": 4,
},
"fields": ["category", "chunk_text"]
"rerank": {
"query": "Disease prevention",
"model": "bge-reranker-v2-m3",
"top_n": 2,
"rank_fields": ["chunk_text"]
}
}'
```
```python Python theme={null}
{'result': {'hits': [{'_id': 'rec3',
'_score': 0.004399413242936134,
'fields': {'category': 'immune system',
'chunk_text': 'Rich in vitamin C and other '
'antioxidants, apples '
'contribute to immune health '
'and may reduce the risk of '
'chronic diseases.'}},
{'_id': 'rec4',
'_score': 0.0029235430993139744,
'fields': {'category': 'endocrine system',
'chunk_text': 'The high fiber content in '
'apples can also help regulate '
'blood sugar levels, making '
'them a favorable snack for '
'people with diabetes.'}}]},
'usage': {'embed_total_tokens': 8, 'read_units': 6, 'rerank_units': 1}}
```
```javascript JavaScript theme={null}
{
"result": {
"hits": [
{
"_id": "rec3",
"_score": 0.004399413242936134,
"fields": {
"category": "immune system",
"chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases."
}
},
{
"_id": "rec4",
"_score": 0.0029235430993139744,
"fields": {
"category": "endocrine system",
"chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes."
}
}
]
},
"usage": {
"readUnits": 6,
"embedTotalTokens": 8,
"rerankUnits": 1
}
}
```
```java Java theme={null}
class SearchRecordsResponse {
result: class SearchRecordsResponseResult {
hits: [class Hit {
id: rec3
score: 0.004399413242936134
fields: {category=immune system, chunk_text=Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.}
additionalProperties: null
}, class Hit {
id: rec4
score: 0.0029235430993139744
fields: {category=endocrine system, chunk_text=The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.}
additionalProperties: null
}]
additionalProperties: null
}
usage: class SearchUsage {
readUnits: 6
embedTotalTokens: 13
rerankUnits: 1
additionalProperties: null
}
additionalProperties: null
}
```
```go Go theme={null}
{
"result": {
"hits": [
{
"_id": "rec3",
"_score": 0.004399413242936134,
"fields": {
"category": "immune system",
"chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases."
}
},
{
"_id": "rec4",
"_score": 0.0029235430993139744,
"fields": {
"category": "endocrine system",
"chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes."
}
}
]
},
"usage": {
"read_units": 6,
"embed_total_tokens": 8,
"rerank_units": 1
}
}
```
```csharp C# theme={null}
{
"result": {
"hits": [
{
"_id": "rec3",
"_score": 0.13741668,
"fields": {
"category": "immune system",
"chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases."
}
},
{
"_id": "rec1",
"_score": 0.0023413408,
"fields": {
"category": "digestive system",
"chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut."
}
}
]
},
"usage": {
"read_units": 6,
"embed_total_tokens": 5,
"rerank_units": 1
}
}
```
```json curl theme={null}
{
"result": {
"hits": [
{
"_id": "rec3",
"_score": 0.004433765076100826,
"fields": {
"category": "immune system",
"chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases."
}
},
{
"_id": "rec4",
"_score": 0.0029121784027665854,
"fields": {
"category": "endocrine system",
"chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes."
}
}
]
},
"usage": {
"embed_total_tokens": 8,
"read_units": 6,
"rerank_units": 1
}
}
```
## OpenAPI
````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-04/db_data_2025-04.oas.yaml post /records/namespaces/{namespace}/search
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:
/records/namespaces/{namespace}/search:
post:
tags:
- Vector Operations
summary: Search with text
description: >-
Search a namespace with a query text, query vector, or record ID and
return the most similar records, along with their similarity scores.
Optionally, rerank the initial results based on their relevance to the
query.
Searching with text is supported only for [indexes with integrated
embedding](https://docs.pinecone.io/guides/indexes/create-an-index#integrated-embedding).
Searching with a query vector or record ID is supported for all
indexes.
For guidance, examples, and limits, see
[Search](https://docs.pinecone.io/guides/search/search-overview).
operationId: searchRecordsNamespace
parameters:
- in: path
name: namespace
description: The namespace to search.
required: true
schema:
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRecordsRequest'
required: true
responses:
'200':
description: A successful search namespace response.
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRecordsResponse'
'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:
SearchRecordsRequest:
example:
fields:
- chunk_text
query:
inputs:
text: your query text
top_k: 10
description: A search request for records in a specific namespace.
type: object
properties:
query:
description: .
type: object
properties:
top_k:
example: 10
description: The number of similar records to return.
type: integer
format: int32
filter:
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
inputs:
$ref: '#/components/schemas/EmbedInputs'
vector:
$ref: '#/components/schemas/SearchRecordsVector'
id:
example: example-vector-1
description: The unique ID of the vector to be used as a query vector.
type: string
maxLength: 512
required:
- top_k
fields:
example:
- chunk_text
description: >-
The fields to return in the search results. If not specified, the
response will include all fields.
type: array
items:
type: string
maxLength: 100
rerank:
description: Parameters for reranking the initial search results.
type: object
properties:
model:
example: bge-reranker-v2-m3
description: >-
The name of the [reranking
model](https://docs.pinecone.io/guides/search/rerank-results#reranking-models)
to use.
type: string
rank_fields:
example:
- chunk_text
- title
description: >
The field(s) to consider for reranking. If not provided, the
default is `["text"]`.
The number of fields supported is
[model-specific](https://docs.pinecone.io/guides/search/rerank-results#reranking-models).
type: array
items:
type: string
top_n:
example: 5
description: >-
The number of top results to return after reranking. Defaults to
top_k.
type: integer
format: int32
parameters:
example:
truncate: END
description: >-
Additional model-specific parameters. Refer to the [model
guide](https://docs.pinecone.io/guides/search/rerank-results#reranking-models)
for available model parameters.
type: object
additionalProperties: true
query:
example: What is the capital of France?
description: >-
The query to rerank documents against. If a specific rerank
query is specified, it overwrites the query input that was
provided at the top level.
type: string
required:
- model
- rank_fields
required:
- query
SearchRecordsResponse:
example:
result:
hits:
- _id: example-record-1
_score: 0.9281134605407715
fields:
data: your example text
usage:
embed_total_tokens: 10
read_units: 5
description: The records search response.
type: object
properties:
result:
type: object
properties:
hits:
description: The hits for the search document request.
type: array
items:
$ref: '#/components/schemas/Hit'
required:
- hits
usage:
$ref: '#/components/schemas/SearchUsage'
required:
- usage
- result
rpcStatus:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
details:
type: array
items:
$ref: '#/components/schemas/protobufAny'
EmbedInputs:
example:
text: chunk_text
type: object
SearchRecordsVector:
type: object
properties:
values:
$ref: '#/components/schemas/VectorValues'
sparse_values:
example:
- 0.1
- 0.2
- 0.3
description: The sparse embedding values.
type: array
items:
type: number
format: float
sparse_indices:
example:
- 10
- 3
- 156
description: The sparse embedding indices.
type: array
items:
type: integer
format: int32
minimum: 0
Hit:
example:
_id: example-record-1
_score: 0.9281134605407715
fields:
data: your example text
more_data:
text: your example text
description: A record whose vector values are similar to the provided search query.
type: object
properties:
_id:
description: The record id of the search hit.
type: string
_score:
description: The similarity score of the returned record.
type: number
format: float
fields:
description: The selected record fields associated with the search hit.
type: object
required:
- _id
- _score
- fields
SearchUsage:
type: object
properties:
read_units:
example: 5
description: The number of read units consumed by this operation.
type: integer
format: int32
minimum: 0
embed_total_tokens:
example: 2
description: The number of embedding tokens consumed by this operation.
type: integer
format: int32
minimum: 0
rerank_units:
example: 1
description: The number of rerank units consumed by this operation.
type: integer
format: int32
minimum: 0
required:
- read_units
protobufAny:
type: object
properties:
typeUrl:
type: string
value:
type: string
format: byte
VectorValues:
description: This is the vector data included in the request.
type: array
items:
type: number
format: float
minLength: 1
maxLength: 20000
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/).
````