Sparse-vector search

This page shows you how to search an index with sparse vectors for documents that most exactly match the words or phrases in a query.

For general-purpose text retrieval (product search, content discovery, document Q&A), we recommend full-text search. Full-text search runs over string fields you’ve declared with full_text_search enabled, using BM25 ranking and Lucene query syntax. The multi-field schema also lets you add dense_vector or sparse_vector ranking later in the same index.Sparse-vector search (this page) is a distinct retrieval mode. Reach for it when you want token-weighted retrieval with sparse vectors, either generated by Pinecone from a sparse_embed field (pinecone-sparse-english-v0 by default) or produced by your own sparse encoder.

Sparse-vector search uses sparse vectors, which have a very large number of dimensions, where only a small proportion of values are non-zero. The dimensions represent words from a dictionary, and the values represent the importance of these words in the document. Words are scored independently and then summed, with the most similar documents scored highest. For a legacy vector index, see Query vectors. For a legacy integrated index, see Search with text.

Search a document index

In a document index, you choose how to score each search with a clause in score_by. Use a sparse_embed clause to search with text, or a sparse_vector clause to search with a sparse vector you generate yourself.

Search with text

To search with text, the string field must declare sparse_embed, which enables integrated embedding. Pinecone converts your query text to a sparse vector with the field’s model. For example, this searches the chunk_text field of an index whose schema declares "chunk_text": {"type": "string", "sparse_embed": {}} and returns the 3 documents that best match “What is AAPL’s outlook, considering both product launches and market conditions?”:

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/indexes/target-an-index
index = pc.index(host="INDEX_HOST")

results = index.documents.search(
    namespace="example-namespace",
    top_k=3,
    score_by=[
        {
            "type": "sparse_embed",
            "fields": ["chunk_text"],
            "query": "What is AAPL's outlook, considering both product launches and market conditions?",
        }
    ],
    include_fields=["chunk_text", "quarter"],
)

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/indexes/target-an-index
const index = pc.index({ host: "INDEX_HOST", namespace: "example-namespace" })

const results = await index.documents.search({
  topK: 3,
  scoreBy: [
    {
      type: 'sparse_embed',
      fields: ['chunk_text'],
      query: "What is AAPL's outlook, considering both product launches and market conditions?",
    },
  ],
  includeFields: ['chunk_text', 'quarter'],
})

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/indexes/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 := "What is AAPL's outlook, considering both product launches and market conditions?"
    res, err := idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{
        TopK: 3,
        ScoreBy: []pinecone.DocumentScoringMethod{
            {Type: pinecone.DocumentScoringTypeSparseEmbed, Fields: []string{"chunk_text"}, Query: &query},
        },
        IncludeFields: []string{"chunk_text", "quarter"},
    })
    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": 3,
            "score_by": [
                {
                    "type": "sparse_embed",
                    "fields": ["chunk_text"],
                    "query": "What is AAPL'\''s outlook, considering both product launches and market conditions?"
                }
            ],
            "include_fields": ["chunk_text", "quarter"]
        }'

To require specific terms in each result, add a $match_all text-match filter on the same field, for example, "filter": {"chunk_text": {"$match_all": "AAPL Q4"}}. This works because Pinecone stores the field’s text and indexes it for full-text search unless the field sets store_text: false.

Search with a sparse vector

To search a sparse_vector field, pass a sparse_vector clause in score_by with the query’s sparse vector, produced by the same encoder you used at upsert. For example, this searches the sparse_embedding field of the articles-hybrid schema:

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/indexes/target-an-index
index = pc.index(host="INDEX_HOST")

results = index.documents.search(
    namespace="articles",
    top_k=3,
    score_by=[
        {
            "type": "sparse_vector",
            "fields": ["sparse_embedding"],
            "sparse_values": {"indices": [10, 45, 16], "values": [0.5, 0.5, 0.2]},
        }
    ],
    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/indexes/target-an-index
const index = pc.index({ host: "INDEX_HOST", namespace: "articles" })

const results = await index.documents.search({
  topK: 3,
  scoreBy: [
    {
      type: 'sparse_vector',
      fields: ['sparse_embedding'],
      sparseValues: { indices: [10, 45, 16], values: [0.5, 0.5, 0.2] },
    },
  ],
  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/indexes/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)
    }

    res, err := idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{
        TopK: 3,
        ScoreBy: []pinecone.DocumentScoringMethod{
            {
                Type:   pinecone.DocumentScoringTypeSparseVector,
                Fields: []string{"sparse_embedding"},
                SparseValues: &pinecone.SparseValues{
                    Indices: []uint32{10, 45, 16},
                    Values:  []float32{0.5, 0.5, 0.2},
                },
            },
        },
        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": "sparse_vector",
                    "fields": ["sparse_embedding"],
                    "sparse_values": { "indices": [10, 45, 16], "values": [0.5, 0.5, 0.2] }
                }
            ],
            "include_fields": ["title"]
        }'

Get started

Indexes

Data

Search

Optimize

Cost

Production

Agents

Legacy

Search a document index

Search with text

Search with a sparse vector

​Search a document index

​Search with text

​Search with a sparse vector

Search a document index

Search with text

Search with a sparse vector