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

# Integrated embedding

> Declare embed or sparse_embed on a string field so Pinecone embeds your text on a document index, and upsert and search with plain text instead of vectors.

Embedding converts text into a vector that captures its meaning. Instead of generating those vectors yourself, you can have Pinecone embed a `string` field's text for you. Add an `embed` (dense) or `sparse_embed` (learned-sparse) object to the field, and Pinecone embeds the text when you upsert or update a [document](https://docs.pinecone.io/guides/indexes/data-modeling.md#documents), and embeds the query text when you search that field. You send and search with plain text and never handle vectors.

This is the same integrated embedding that the [Create an index with integrated embedding](https://docs.pinecone.io/reference/api/2026-07/control-plane/create_for_model.md) operation provides for the legacy Records API, brought to document indexes, where it composes with full-text search on the same field.

Integrated embedding requires API version `2026-07`. Send `X-Pinecone-Api-Version: 2026-07` on REST requests, or use an SDK that supports it: Python `10.1.0` or later, Node.js `9.1.0` or later, or Go `7.1.0` or later.

> [!NOTE]
>
> Bring Your Own Cloud (BYOC) indexes can't declare `embed` or `sparse_embed`.

## Declare an embedded field

Add `embed`, `sparse_embed`, or both to a `string` field, inside `schema.fields` in the [create-index request](https://docs.pinecone.io/guides/search/full-text-search.md#example-schemas). Every key inside them is optional: an empty `{}` uses the platform default model at its default dimension and metric. Pinecone resolves and fixes the model, dimension, and metric at creation, and returns them when you describe the index.

> [!TIP]
>
> You can also create an index with integrated embedding in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/schema-create-index).

```json Default models theme={null}
{
  "chunk_text": {
    "type": "string",
    "embed": {},
    "sparse_embed": {}
  }
}
```

```json Chosen model and dimension theme={null}
{
  "chunk_text": {
    "type": "string",
    "embed": { "model": "llama-text-embed-v2", "dimension": 512 }
  }
}
```

* `embed` takes a hosted dense model (default [`llama-text-embed-v2`](https://docs.pinecone.io/models/llama-text-embed-v2)) and optional `dimension`, `metric`, [`processing_location`](https://docs.pinecone.io/guides/indexes/processing-locations), and `write_parameters`/`read_parameters` (model parameters applied when embedding on write and on query, such as `truncate` or [`task_type`](#task-types) for `gemini-embedding-2`).
* `sparse_embed` takes a hosted sparse model (default [`pinecone-sparse-english-v0`](https://docs.pinecone.io/models/pinecone-sparse-english-v0)) and optional `write_parameters`/`read_parameters`. Sparse embeddings have no dimension or metric.
* An `embed` field uses the index's single dense slot, and a `sparse_embed` field uses its single sparse slot. So an index has at most one of each, and an embedded field can't coexist with a `dense_vector` or `sparse_vector` field of the same type (dense or sparse).

To compare the hosted models and the dimensions each one supports, see the [model gallery](https://docs.pinecone.io/models/overview.md). `llama-text-embed-v2` takes one of a fixed set of dimensions, while `gemini-embedding-2` and the `text-embedding-3` models take any integer in a range. The embedding configuration is fixed at creation: you can't add, remove, or change `embed` or `sparse_embed` on an existing index.

## Text storage and full-text search

By default (`store_text: true`), Pinecone stores the field's text and returns it via `include_fields`. It also indexes the text for full-text search, so a `string` field with `embed` is BM25-searchable unless you opt out.

Set `store_text: false` to embed the text without storing it. A field with `store_text: false`:

* can't declare `full_text_search`.
* can't be scored with `text` or `query_string`, or matched with `$match_phrase`, `$match_all`, or `$match_any`.
* still supports `embed` and `sparse_embed` scoring.
* returns a `400` if named in `include_fields` on search or fetch. `["*"]` leaves it out.

To search one chunk field by dense, learned-sparse, and BM25, declare all three aspects:

```json All three aspects theme={null}
{
  "chunk_text": {
    "type": "string",
    "embed": {},
    "sparse_embed": {},
    "full_text_search": {}
  }
}
```

### Limits

* A document and a single request are each limited to 2 MB. On an index that embeds text, that request limit also counts the vectors Pinecone derives from the text.
* An embedded value can be up to 100 KB, whether or not the text is stored. A stored value is also limited to 10,000 tokens after tokenization.
* Each model embeds only up to its max tokens, listed in the [model gallery](https://docs.pinecone.io/models/overview.md). For `pinecone-sparse-english-v0`, that's its [`max_tokens_per_sequence`](https://docs.pinecone.io/models/pinecone-sparse-english-v0#parameters) parameter. Longer values are truncated by default. For a dense `embed` field, setting `truncate: NONE` rejects an over-length value with a `400` instead. The full value is still stored and returned when `store_text` is `true`.
* Truncation applies only to embedding, so a stored value over 10,000 tokens is rejected with a `400` even with `truncate: END`. To embed longer text, split it into smaller documents, or set `store_text: false` to embed it without storing it.
* The query text in an `embed` or `sparse_embed` clause is limited to 10,000 bytes. A longer query is rejected with a `400`, not truncated.

## Upsert and search embedded fields

### Upsert

Upsert documents with plain text on the embedded field. You don't supply vectors, and Pinecone embeds the text on write. A few rules apply:

* When the schema declares `embed` or `sparse_embed`, each upsert or by-ID update is embedded in one call, so it's capped at 96 documents instead of 1,000, even when a request sets only metadata.
* A dense `embed` field must appear in every document. Omitting it, or removing it in an update, is rejected with a `400`. A `sparse_embed`-only field is optional, so you can omit or remove it.
* A vector or an empty string on an embedded field is rejected with a `400`.
* Update is a partial patch, so a field you don't set is left unchanged. A by-filter update can't set an embedded field; patch it by document ID.
* An update to an `_id` that doesn't exist has no effect, but any text it sets is still embedded and metered. To add a new document, upsert it.
* An upsert or update that embeds text reports the tokens it consumed as `usage.embed_total_tokens`. It's one total across all fields and models, so a field with both `embed` and `sparse_embed` reports the dense and sparse tokens added together. Billing and [monthly limits](https://docs.pinecone.io/reference/api/database-limits/rate-limits.md#monthly-usage-limits) count tokens per model, so sparse tokens count toward the field's sparse model, not its dense model.

```python Python theme={null}
index.documents.upsert(
    namespace="example-namespace",
    documents=[
        {"_id": "doc1", "chunk_text": "Vitamin D supports bone health and immune function."},
    ],
)
```

```javascript JavaScript theme={null}
const index = pc.index({ name: 'INDEX_NAME', namespace: 'example-namespace' });

await index.documents.upsert({
  documents: [
    { _id: 'doc1', chunk_text: 'Vitamin D supports bone health and immune function.' },
  ],
});
```

```go Go theme={null}
idx, _ := pc.DescribeIndex(ctx, "INDEX_NAME")
conn, _ := pc.Index(pinecone.NewIndexConnParams{Host: idx.Host, Namespace: "example-namespace"})

_, err := conn.UpsertDocuments(ctx, &pinecone.UpsertDocumentsRequest{
	Documents: []pinecone.Document{
		{"_id": "doc1", "chunk_text": "Vitamin D supports bone health and immune function."},
	},
})
if err != nil {
	log.Fatal(err)
}
```

> [!NOTE]
>
> You can't [bulk import](https://docs.pinecone.io/guides/data/import-data.md) into an index with an `embed` or `sparse_embed` field. Add text through upsert or update instead.

### Search

To search, pick the `embed` or `sparse_embed` scoring method and pass query text. Pinecone embeds the query with the field's frozen model and ranks by similarity.

```python Python theme={null}
response = index.documents.search(
    namespace="example-namespace",
    top_k=5,
    score_by=[
        {"type": "embed", "fields": ["chunk_text"], "query": "how does vitamin D help the body"}
    ],
    include_fields=["chunk_text"],
)
```

```javascript JavaScript theme={null}
const index = pc.index({ name: 'INDEX_NAME', namespace: 'example-namespace' });

const response = await index.documents.search({
  topK: 5,
  scoreBy: [
    { type: 'embed', fields: ['chunk_text'], query: 'how does vitamin D help the body' },
  ],
  includeFields: ['chunk_text'],
});
```

```go Go theme={null}
idx, _ := pc.DescribeIndex(ctx, "INDEX_NAME")
conn, _ := pc.Index(pinecone.NewIndexConnParams{Host: idx.Host, Namespace: "example-namespace"})

query := "how does vitamin D help the body"
response, err := conn.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{
	TopK: 5,
	ScoreBy: []pinecone.DocumentScoringMethod{
		{Type: pinecone.DocumentScoringTypeEmbed, Fields: []string{"chunk_text"}, Query: &query},
	},
	IncludeFields: []string{"chunk_text"},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(response)
```

```bash curl theme={null}
curl -X POST "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": 5,
    "score_by": [
      { "type": "embed", "fields": ["chunk_text"], "query": "how does vitamin D help the body" }
    ],
    "include_fields": ["chunk_text"]
  }'
```

Pinecone returns the stored text and any metadata you request with `include_fields`. The vectors it derives from your text are internal and aren't returned. The search response reports the query's embedding usage as `usage.embed_total_tokens`. A `sparse_embed` query is embedded in-process, so it reports `0`.

An `embed` or `sparse_embed` clause must be the only clause in `score_by`. You can still combine signals, because a stored embedded field is also full-text-searchable. Rank with an `embed` `score_by`, then narrow the results with a `$match_phrase`, `$match_all`, or `$match_any` filter on the same field (see [Full-text search](https://docs.pinecone.io/guides/search/full-text-search.md#search-examples)). To fuse two full rankings instead, run separate searches and merge them with [reciprocal rank fusion](https://docs.pinecone.io/guides/search/reciprocal-rank-fusion.md).

## Embed with text-embedding-3

[`text-embedding-3-small`](https://docs.pinecone.io/models/text-embedding-3-small) and [`text-embedding-3-large`](https://docs.pinecone.io/models/text-embedding-3-large) are dense models from OpenAI that are available only on document indexes. Pinecone embeds text for them through Microsoft Azure. Each model's page lists its dimensions, token limit, metrics, and parameters.

The models are available on every plan. They process text in the `global` [processing location](https://docs.pinecone.io/guides/indexes/processing-locations.md) by default, and you can set `processing_location` to `us` on the Standard and Enterprise plans. For monthly and per-minute token limits, see [Rate limits](https://docs.pinecone.io/reference/api/database-limits/rate-limits.md).

This field embeds with `text-embedding-3-large` at 1,024 dimensions:

```json Shortened large embeddings theme={null}
{
  "chunk_text": {
    "type": "string",
    "embed": { "model": "text-embedding-3-large", "dimension": 1024 }
  }
}
```

## Embed with gemini-embedding-2

[`gemini-embedding-2`](https://docs.pinecone.io/models/gemini-embedding-2) is a dense model from Google that's available only on document indexes. Pinecone embeds text for it through Google Vertex AI. The model page lists its dimensions, token limit, metric, and parameters.

The model isn't available on the Starter plan. Creating an index with it on Starter returns a `403` that names the field and model. If your organization moves to the Starter plan, its existing `gemini-embedding-2` indexes stay, but upserts and searches on them return a `403` until you upgrade again. For monthly and per-minute token limits, see [Rate limits](https://docs.pinecone.io/reference/api/database-limits/rate-limits.md).

### Task types

`gemini-embedding-2` embeds text differently depending on what the embedding is for. You choose this with the `task_type` parameter. Each task belongs to one of three kinds:

* **Write task**: `retrieval_document` embeds the stored text of a field you search.
* **Query tasks**: These embed search queries against a `retrieval_document` field.
* **Symmetric tasks**: These embed stored text and queries the same way, for comparing texts with each other rather than searching.

Pinecone adds the task to each value and query as the short prompt Gemini expects, so you send plain text. For every task type, what it's for, and its prompt, see [Task types](https://docs.pinecone.io/models/gemini-embedding-2#task-types) on the model page.

### Set task types on the field

Set `task_type` in the field's `write_parameters` and `read_parameters`:

* `write_parameters.task_type` sets how Pinecone embeds the stored text. It defaults to `retrieval_document` and accepts `retrieval_document` or a symmetric task. A query task is rejected with a `400`.
* `read_parameters.task_type` sets the default task for queries. If you don't set it, it follows the write task: `retrieval_query` for a `retrieval_document` field, or the same task for a symmetric field.
* A `retrieval_document` field accepts any query task on read. A symmetric field accepts only its own task, so a `clustering` field is always searched with `clustering`.
* The write task is fixed at creation, like the rest of the embedding configuration. An index has one `embed` field, so to embed the same text for a different write task, such as `retrieval_document` and `clustering`, create a second index.

This field stores articles for search and embeds queries as questions by default:

```json Questions against articles theme={null}
{
  "body": {
    "type": "string",
    "embed": {
      "model": "gemini-embedding-2",
      "dimension": 768,
      "read_parameters": { "task_type": "question_answering" }
    }
  }
}
```

This field embeds support tickets for clustering, and its queries use `clustering` too:

```json Clustered tickets theme={null}
{
  "ticket_text": {
    "type": "string",
    "embed": {
      "model": "gemini-embedding-2",
      "write_parameters": { "task_type": "clustering" }
    }
  }
}
```

When you describe the index, the field's `write_parameters` and `read_parameters` show the resolved task types.

### Override the task for one search

To embed one search's query with a different task, set `parameters` on the `embed` clause. It overrides the field's `read_parameters` for that search only. The Python SDK `10.3.0`, Node.js SDK `9.2.0`, and Go SDK `7.2.0` and later support `parameters`. For example, this search checks a statement against the `body` field from the preceding example, whose default query task is `question_answering`:

```python Python theme={null}
response = index.documents.search(
    namespace="example-namespace",
    top_k=5,
    score_by=[
        {
            "type": "embed",
            "fields": ["body"],
            "query": "Is the Eiffel Tower taller than 300 m?",
            "parameters": {"task_type": "fact_verification"},
        }
    ],
    include_fields=["body"],
)
```

```javascript JavaScript theme={null}
const response = await index.documents.search({
  topK: 5,
  scoreBy: [
    {
      type: 'embed',
      fields: ['body'],
      query: 'Is the Eiffel Tower taller than 300 m?',
      parameters: { task_type: 'fact_verification' },
    },
  ],
  includeFields: ['body'],
});
```

```go Go theme={null}
query := "Is the Eiffel Tower taller than 300 m?"
response, err := conn.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{
	TopK: 5,
	ScoreBy: []pinecone.DocumentScoringMethod{
		{
			Type:       pinecone.DocumentScoringTypeEmbed,
			Fields:     []string{"body"},
			Query:      &query,
			Parameters: map[string]interface{}{"task_type": "fact_verification"},
		},
	},
	IncludeFields: []string{"body"},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(response)
```

```bash curl theme={null}
curl -X POST "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": 5,
    "score_by": [
      {
        "type": "embed",
        "fields": ["body"],
        "query": "Is the Eiffel Tower taller than 300 m?",
        "parameters": { "task_type": "fact_verification" }
      }
    ],
    "include_fields": ["body"]
  }'
```

These rules apply to `parameters`:

* Only `embed` clauses take `parameters`, and only `task_type` can be set per search. Any other key, such as `truncate`, is rejected with a `400`.
* The task must be one the field accepts on read. A query task on a symmetric field, or `retrieval_document` on any field, is rejected with a `400` that names the tasks the field allows.
* A model without task types, such as `llama-text-embed-v2`, rejects `parameters.task_type` with a `400`.
* An empty `parameters` object has no effect.
* Upserts and updates don't take a per-request task. Stored text always uses the field's write task.

## Find a model's parameters

Each model's page in the [model gallery](https://docs.pinecone.io/models/overview.md) lists the parameters it accepts. The [List models](https://docs.pinecone.io/reference/api/latest/inference/list-available-models.md) operation also returns each model's `supported_parameters` with their accepted values. It doesn't say which parameters apply on write, on read, or per search, so use the rules on this page for `task_type` and [Processing locations](https://docs.pinecone.io/guides/indexes/processing-locations.md) for `processing_location`. List models doesn't require an API key.
