Skip to main content
Pinecone Docs

Search documentation

Type to search this documentation.

On this pageOverview

Search with text

Searching with text is supported only for indexes with integrated embedding. Searching with a query vector or record ID is supported for all indexes.

For guidance, examples, and limits, see Search.

Python
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
// 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
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<String> fields = new ArrayList<>();
        fields.add("category");
        fields.add("chunk_text");
        List<String>rankFields = 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
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))
}
C#
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<string, object?> { { "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);
curl
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
{'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
{
  "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
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
{
  "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
  }
}
C#
{
    "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
    }
}
curl
{
    "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
    }
}

POST /records/namespaces/{namespace}/search

Parameters

Section titled “Parameters”
  • namespace (path, string, required) — The namespace to search.

Request body

Section titled “Request body”
  • query (body, object, required) — .
  • fields (body, string[]) — The fields to return in the search results. If not specified, the response will include all fields.
  • rerank (body, object) — Parameters for reranking the initial search results.

Responses

Section titled “Responses”
  • 200 — A successful search namespace response.
  • 400 — Bad request. The request body included invalid request parameters.
  • 4XX — An unexpected error response.
  • 5XX — 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