> ## 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.

# Sparse-vector search

> Run sparse-vector search in Pinecone over a document index, querying with text or with a sparse vector you generate.

This page shows you how to search an [index with sparse vectors](https://docs.pinecone.io/guides/indexes/index-data-overview.md#sparse-vector-search) for documents that most exactly match the words or phrases in a query.

> [!NOTE]
>
> For general-purpose text retrieval (product search, content discovery, document Q\&A), we recommend [full-text search](https://docs.pinecone.io/guides/search/full-text-search.md). 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`](https://docs.pinecone.io/models/pinecone-sparse-english-v0) by default) or produced by your own sparse encoder.

Sparse-vector search uses [sparse vectors](https://www.pinecone.io/learn/sparse-retrieval/), 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.

Sparse-vector search and full-text search both match on tokens, but they weight them differently. Full-text search uses BM25, a statistical function with no model. Sparse-vector search uses the weights in your sparse vectors. With a learned encoder such as `pinecone-sparse-english-v0`, those weights come from a model and can include related terms that don't appear in the text.

For a legacy vector index, see [Query vectors](https://docs.pinecone.io/guides/legacy/vectors-api/query-vectors.md#query-with-sparse-vectors). For a legacy integrated index, see [Search with text](https://docs.pinecone.io/guides/legacy/records-api/search-with-text.md#search-with-sparse-embedding).

## Search a document index

In a [document index](https://docs.pinecone.io/guides/indexes/data-modeling.md#documents), 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](https://docs.pinecone.io/guides/search/integrated-embedding.md). 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?":

```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/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"],
)
```

```javascript JavaScript theme={null}
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)
```

```go Go theme={null}
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))
}
```

```bash curl theme={null}
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](https://docs.pinecone.io/guides/search/filter-by-metadata.md#text-match-filters) 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](https://docs.pinecone.io/guides/search/full-text-search#example-schemas):

```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/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"],
)
```

```javascript JavaScript theme={null}
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)
```

```go Go theme={null}
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))
}
```

```bash curl theme={null}
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"]
        }'
```
