Semantic search

Semantic search finds the documents or records in an index with dense vectors that are most similar in meaning and context to a query. It’s also called nearest neighbor search, similarity search, or vector search. Semantic search uses dense vectors. Each number in a dense vector corresponds to a point in a multidimensional space. Vectors that are closer together in that space are semantically similar.

Search a document index

In a document index, you choose how to score each search with a clause in score_by. Use an embed clause to search with text, or a dense_vector clause to search with a dense vector you generate yourself.

Search with text

To search with text, the string field must declare embed, which enables integrated embedding. Pinecone embeds your query text with the field’s model. For example, this searches the chunk_text field of an index whose schema declares "chunk_text": {"type": "string", "embed": {}} and returns the 2 documents most semantically related to “Disease prevention”:

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(host="INDEX_HOST")

results = index.documents.search(
    namespace="example-namespace",
    top_k=2,
    score_by=[
        {"type": "embed", "fields": ["chunk_text"], "query": "Disease prevention"}
    ],
    include_fields=["chunk_text", "category"],
)

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({ host: "INDEX_HOST", namespace: "example-namespace" })

const results = await index.documents.search({
  topK: 2,
  scoreBy: [
    { type: 'embed', fields: ['chunk_text'], query: 'Disease prevention' },
  ],
  includeFields: ['chunk_text', 'category'],
})

console.log(results)

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"

    "github.com/pinecone-io/go-pinecone/v7/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)
    }

    query := "Disease prevention"
    res, err := idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{
        TopK: 2,
        ScoreBy: []pinecone.DocumentScoringMethod{
            {Type: pinecone.DocumentScoringTypeEmbed, Fields: []string{"chunk_text"}, Query: &query},
        },
        IncludeFields: []string{"chunk_text", "category"},
    })
    if err != nil {
        log.Fatalf("Failed to search documents: %v", err)
    }
    fmt.Println(prettifyStruct(res))
}

PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"

curl "https://$INDEX_HOST/namespaces/example-namespace/documents/search" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-07" \
    -d '{
            "top_k": 2,
            "score_by": [
                {
                    "type": "embed",
                    "fields": ["chunk_text"],
                    "query": "Disease prevention"
                }
            ],
            "include_fields": ["chunk_text", "category"]
        }'

Search with a dense vector

To search a dense_vector field, pass a dense_vector clause in score_by with the query’s dense vector. Generate the query vector with the same embedding model you used at upsert. For example, this searches the embedding field of the articles-hybrid schema, so the query vector must have 1536 dimensions:

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(host="INDEX_HOST")

results = index.documents.search(
    namespace="articles",
    top_k=3,
    score_by=[
        {
            "type": "dense_vector",
            "fields": ["embedding"],
            "values": [0.0236663818359375, -0.032989501953125, ..., 0.0086669921875],
        }
    ],
    include_fields=["title"],
)

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({ host: "INDEX_HOST", namespace: "articles" })

const results = await index.documents.search({
  topK: 3,
  scoreBy: [
    { type: 'dense_vector', fields: ['embedding'], values: [0.0236663818359375, -0.032989501953125, ..., 0.0086669921875] },
  ],
  includeFields: ['title'],
})

console.log(results)

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"

    "github.com/pinecone-io/go-pinecone/v7/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: "articles"})
    if err != nil {
        log.Fatalf("Failed to create IndexConnection for Host: %v", err)
    }

    queryVector := []float32{0.0236663818359375, -0.032989501953125, ..., 0.0086669921875}
    res, err := idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{
        TopK: 3,
        ScoreBy: []pinecone.DocumentScoringMethod{
            {Type: pinecone.DocumentScoringTypeDenseVector, Fields: []string{"embedding"}, Values: &queryVector},
        },
        IncludeFields: []string{"title"},
    })
    if err != nil {
        log.Fatalf("Failed to search documents: %v", err)
    }
    fmt.Println(prettifyStruct(res))
}

PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"

curl "https://$INDEX_HOST/namespaces/articles/documents/search" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-07" \
    -d '{
            "top_k": 3,
            "score_by": [
                {
                    "type": "dense_vector",
                    "fields": ["embedding"],
                    "values": [0.0236663818359375, -0.032989501953125, ..., 0.0086669921875]
                }
            ],
            "include_fields": ["title"]
        }'

Search a vector index

In a vector index, the query is either a dense vector or the ID of a record whose vector Pinecone uses as the query.

Search with a dense vector

To search with a dense vector representation of a query, use the Search with a vector operation with the following parameters:

The namespace to query. To use the default namespace, set the namespace to "__default__".
The vector parameter with the dense vector values representing your query.
The top_k parameter with the number of results to return.
Optionally, set include_values, include_metadata, or both to true to include the vector values, metadata, or both for the matching records in the response. For better performance, especially with higher top_k values, avoid including vector values unless you need them. See Decrease latency for more details.

For example, the following code uses a dense vector representation of the query “Disease prevention” to search for the 3 most semantically similar records in the example-namespace namespace:

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.0236663818359375,-0.032989501953125, ..., -0.01041412353515625,0.0086669921875], 
    top_k=3,
    include_metadata=True,
    include_values=False
)

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.0236663818359375,-0.032989501953125,...,-0.01041412353515625,0.0086669921875],
    topK: 3,
    includeValues: false,
    includeMetadata: true,
});

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<Float> query = Arrays.asList(0.0236663818359375f, -0.032989501953125f, ..., -0.01041412353515625f, 0.0086669921875f);
        QueryResponseWithUnsignedIndices queryResponse = index.query(3, query, null, null, null, "example-namespace", null, false, true);
        System.out.println(queryResponse);
    }
}

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"

    "github.com/pinecone-io/go-pinecone/v7/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)
  	}

    queryVector := []float32{0.0236663818359375,-0.032989501953125,...,-0.01041412353515625,0.0086669921875}

    res, err := idxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{
        Vector:          queryVector,
        TopK:            3,
        IncludeValues:   false,
        IncludeMetadata: true,
    })
    if err != nil {
        log.Fatalf("Error encountered when querying by vector: %v", err)
    } else {
        fmt.Println(prettifyStruct(res))
    }
}

# To get the unique host for an index,
# see https://docs.pinecone.io/guides/manage-data/target-an-index
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: 2026-07" \
  -d '{
        "vector": [0.0236663818359375,-0.032989501953125,...,-0.01041412353515625,0.0086669921875],
        "namespace": "example-namespace",
        "topK": 3,
        "includeMetadata": true,
        "includeValues": false
    }'

In the response, each record has a similarity score that represents its distance to the query vector, calculated according to the index’s similarity metric:

{'matches': [{'id': 'rec3',
              'metadata': {'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.'},
              'score': 0.82026422,
              'values': []},
             {'id': 'rec1',
              'metadata': {'category': 'digestive system',
                           'chunk_text': 'Apples are a great source of '
                                          'dietary fiber, which supports '
                                          'digestion and helps maintain a '
                                          'healthy gut.'},
              'score': 0.793068111,
              'values': []},
             {'id': 'rec4',
              'metadata': {'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.'},
              'score': 0.780169606,
              'values': []}],
 'namespace': 'example-namespace',
 'usage': {'read_units': 6}}

{
  matches: [
    {
      id: 'rec3',
      score: 0.819709897,
      values: [],
      sparseValues: undefined,
      metadata: [Object]
    },
    {
      id: 'rec1',
      score: 0.792900264,
      values: [],
      sparseValues: undefined,
      metadata: [Object]
    },
    {
      id: 'rec4',
      score: 0.780068815,
      values: [],
      sparseValues: undefined,
      metadata: [Object]
    }
  ],
  namespace: 'example-namespace',
  usage: { readUnits: 6 }
}

class QueryResponseWithUnsignedIndices {
    matches: [ScoredVectorWithUnsignedIndices {
        score: 0.8197099
        id: rec3
        values: []
        metadata: fields {
          key: "category"
          value {
            string_value: "immune system"
          }
        }
        fields {
          key: "chunk_text"
          value {
            string_value: "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases."
          }
        }
        
        sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices {
            indicesWithUnsigned32Int: []
            values: []
        }
    }, ScoredVectorWithUnsignedIndices {
        score: 0.79290026
        id: rec1
        values: []
        metadata: fields {
          key: "category"
          value {
            string_value: "digestive system"
          }
        }
        fields {
          key: "chunk_text"
          value {
            string_value: "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut."
          }
        }
        
        sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices {
            indicesWithUnsigned32Int: []
            values: []
        }
    }, ScoredVectorWithUnsignedIndices {
        score: 0.7800688
        id: rec4
        values: []
        metadata: fields {
          key: "category"
          value {
            string_value: "endocrine system"
          }
        }
        fields {
          key: "chunk_text"
          value {
            string_value: "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes."
          }
        }
        
        sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices {
            indicesWithUnsigned32Int: []
            values: []
        }
    }]
    namespace: example-namespace
    usage: read_units: 6

}

{
  "matches": [
    {
      "vector": {
        "id": "rec3",
        "metadata": {
          "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."
        }
      },
      "score": 0.8197099
    },
    {
      "vector": {
        "id": "rec1",
        "metadata": {
          "category": "digestive system",
          "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut."
        }
      },
      "score": 0.79290026
    },
    {
      "vector": {
        "id": "rec4",
        "metadata": {
          "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."
        }
      },
      "score": 0.7800688
    }
  ],
  "usage": {
    "read_units": 6
  },
  "namespace": "example-namespace"
}

{
    "results": [],
    "matches": [
        {
            "id": "rec3",
            "score": 0.820593238,
            "values": [],
            "metadata": {
                "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.792266726,
            "values": [],
            "metadata": {
                "category": "digestive system",
                "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut."
            }
        },
        {
            "id": "rec4",
            "score": 0.780045748,
            "values": [],
            "metadata": {
                "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."
            }
        }
    ],
    "namespace": "example-namespace",
    "usage": {
        "readUnits": 6
    }
}

Search with a record ID

When you search with a record ID, Pinecone uses the dense vector associated with the record as the query. Because search is approximate, the results aren’t guaranteed to include that record, even with a high top_k. To retrieve a specific record, fetch it by ID. To search with a record ID, use the Search with a vector operation with the following parameters:

The namespace to query. To use the default namespace, set the namespace to "__default__".
The id parameter with the unique record ID containing the vector to use as the query.
The top_k parameter with the number of results to return.
Optionally, set include_values, include_metadata, or both to true to include the vector values, metadata, or both for the matching records in the response. For better performance, especially with higher top_k values, avoid including vector values unless you need them. See Decrease latency for more details.

For example, the following code uses an ID to search for the 3 records in the example-namespace namespace that are most semantically similar to the dense vector in the record:

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",
    id="rec2", 
    top_k=3,
    include_metadata=True,
    include_values=False
)

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({
    id: 'rec2',
    topK: 3,
    includeValues: false,
    includeMetadata: true,
});

import io.pinecone.clients.Index;
import io.pinecone.configs.PineconeConfig;
import io.pinecone.configs.PineconeConnection;
import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices;

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");
        QueryResponseWithUnsignedIndices queryResponse = index.queryByVectorId(3, "rec2", "example-namespace", null, false, true);
        System.out.println(queryResponse);
    }
}

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"

    "github.com/pinecone-io/go-pinecone/v7/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)
  	}

    vectorId := "rec2"
    res, err := idxConnection.QueryByVectorId(ctx, &pinecone.QueryByVectorIdRequest{
        VectorId:      vectorId,
        TopK:          3,
        IncludeValues: false,
        IncludeMetadata: true,
    })
    if err != nil {
        log.Fatalf("Error encountered when querying by vector ID `%v`: %v", vectorId, err)
    } else {
        fmt.Println(prettifyStruct(res.Matches))
    }
}

# To get the unique host for an index,
# see https://docs.pinecone.io/guides/manage-data/target-an-index
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: 2026-07" \
  -d '{
        "id": "rec2",
        "namespace": "example-namespace",
        "topK": 3,
        "includeMetadata": true,
        "includeValues": false
    }'

Search a legacy integrated index

Legacy integrated indexes are created with create_index_for_model and searched through the legacy Records API. For new indexes, declare embed on a string field in a document index instead. See Integrated embedding.

To search a legacy integrated index with query text, use the Search with text operation with the following parameters:

The namespace to query. To use the default namespace, set the namespace to "__default__".
The query.inputs.text parameter with the query text. Pinecone uses the embedding model integrated with the index to convert the text to a dense vector automatically.
The query.top_k parameter with the number of similar records to return.
Optionally, the fields to return in the response. If you don’t specify any, the response includes all fields.

For example, the following code searches for the 2 records most semantically related to the query text “Disease prevention”:

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(host="INDEX_HOST")

results = index.search(
    namespace="example-namespace", 
    query={
        "inputs": {"text": "Disease prevention"}, 
        "top_k": 2
    },
    fields=["category", "chunk_text"]
)

print(results)

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");

const response = await namespace.searchRecords({
  query: {
    topK: 2,
    inputs: { text: 'Disease prevention' },
  },
  fields: ['chunk_text', 'category'],
});

console.log(response);

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.SearchRecordsResponse;

import java.util.*;

public class SearchText {
    public static void main(String[] args) throws ApiException {
        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(config, connection, "integrated-dense-java");

        String query = "Disease prevention";
        List<String> fields = new ArrayList<>();
        fields.add("category");
        fields.add("chunk_text");

        // Search the index
        SearchRecordsResponse recordsResponse = index.searchRecordsByText(query,  "example-namespace", fields, 2, null, null);

        // Print the results
        System.out.println(recordsResponse);
    }
}

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"

    "github.com/pinecone-io/go-pinecone/v7/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)
    } 

    res, err := idxConnection.SearchRecords(ctx, &pinecone.SearchRecordsRequest{
        Query: pinecone.SearchRecordsQuery{
            TopK: 2,
            Inputs: &map[string]interface{}{
                "text": "Disease prevention",
            },
        },
        Fields: &[]string{"chunk_text", "category"},
    })
    if err != nil {
        log.Fatalf("Failed to search records: %v", err)
    }
    fmt.Println(prettifyStruct(res))
}

INDEX_HOST="INDEX_HOST"
NAMESPACE="YOUR_NAMESPACE"
PINECONE_API_KEY="YOUR_API_KEY"

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: 2026-07" \
  -d '{
        "query": {
            "inputs": {"text": "Disease prevention"},
            "top_k": 2
        },
        "fields": ["category", "chunk_text"]
     }'

In the response, each record has a similarity score that represents its distance to the query vector, calculated according to the index’s similarity metric:

{'result': {'hits': [{'_id': 'rec3',
                      '_score': 0.8204272389411926,
                      '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.7931625843048096,
                      'fields': {'category': 'digestive system',
                                 'chunk_text': 'Apples are a great source of '
                                               'dietary fiber, which supports '
                                               'digestion and helps maintain a '
                                               'healthy gut.'}}]},
 'usage': {'embed_total_tokens': 8, 'read_units': 6}}

{
  result: { 
    hits: [ 
      {
        _id: 'rec3',
        _score: 0.82042724,
        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.7931626,
        fields: {
          category: 'digestive system',
          chunk_text: 'Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.'
        }
      }
    ]
  },
  usage: { 
    readUnits: 6, 
    embedTotalTokens: 8 
  }
}

class SearchRecordsResponse {
    result: class SearchRecordsResponseResult {
        hits: [class Hit {
            id: rec3
            score: 0.8204272389411926
            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: rec1
            score: 0.7931625843048096
            fields: {category=endocrine system, chunk_text=Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.}
            additionalProperties: null
        }]
        additionalProperties: null
    }
    usage: class SearchUsage {
        readUnits: 6
        embedTotalTokens: 13
    }
    additionalProperties: null
}

{
  "result": {
    "hits": [
      {
        "_id": "rec3",
        "_score": 0.82042724,
        "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.7931626,
        "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": 8
  }
}

 {
    "result": {
        "hits": [
            {
                "_id": "rec3",
                "_score": 0.82042724,
                "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.7931626,
                "fields": {
                    "category": "digestive system",
                    "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut."
                }
            }
        ]
    },
    "usage": {
        "embed_total_tokens": 8,
        "read_units": 6
    }
}

Get started

Index data

Search

Optimize

Manage data

Manage cost

Move to production

Agents

Pod-based indexes (legacy)

Search a document index

Search with text

Search with a dense vector

Search a vector index

Search with a dense vector

Search with a record ID

Search a legacy integrated index

​Search a document index

​Search with text

​Search with a dense vector

​Search a vector index

​Search with a dense vector

​Search with a record ID

​Search a legacy integrated index

Search a document index

Search with text

Search with a dense vector

Search a vector index

Search with a dense vector

Search with a record ID

Search a legacy integrated index