Integrated embedding

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

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

You can also create an index with integrated embedding in the Pinecone console.

{
  "chunk_text": {
    "type": "string",
    "embed": {},
    "sparse_embed": {}
  }
}

{
  "chunk_text": {
    "type": "string",
    "embed": { "model": "llama-text-embed-v2", "dimension": 512 }
  }
}

embed takes a hosted dense model (default llama-text-embed-v2) and optional dimension, metric, processing_location, and write_parameters/read_parameters (model parameters applied when embedding on write and on query, such as truncate or task_type for gemini-embedding-2).
sparse_embed takes a hosted sparse model (default 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. 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:

All three aspects

{
  "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. For pinecone-sparse-english-v0, that’s its max_tokens_per_sequence 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 count tokens per model, so sparse tokens count toward the field’s sparse model, not its dense model.

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

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.' },
  ],
});

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)
}

You can’t bulk import 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.

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

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'],
});

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)

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). To fuse two full rankings instead, run separate searches and merge them with reciprocal rank fusion.

Embed with text-embedding-3

text-embedding-3-small and 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 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. This field embeds with text-embedding-3-large at 1,024 dimensions:

Shortened large embeddings

{
  "chunk_text": {
    "type": "string",
    "embed": { "model": "text-embedding-3-large", "dimension": 1024 }
  }
}

Embed with gemini-embedding-2

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.

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 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:

Questions against articles

{
  "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:

Clustered tickets

{
  "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:

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

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'],
});

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)

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 lists the parameters it accepts. The List models 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 for processing_location. List models doesn’t require an API key.

Get started

Indexes

Data

Search

Optimize

Cost

Production

Agents

Legacy

Declare an embedded field

Text storage and full-text search

Limits

Upsert and search embedded fields

Upsert

Search

Embed with text-embedding-3

Embed with gemini-embedding-2

Task types

Set task types on the field

Override the task for one search

Find a model’s parameters

​Declare an embedded field

​Text storage and full-text search

​Limits

​Upsert and search embedded fields

​Upsert

​Search

​Embed with text-embedding-3

​Embed with gemini-embedding-2

​Task types

​Set task types on the field

​Override the task for one search

​Find a model’s parameters

Declare an embedded field

Text storage and full-text search

Limits

Upsert and search embedded fields

Upsert

Search

Embed with text-embedding-3

Embed with gemini-embedding-2

Task types

Set task types on the field

Override the task for one search

Find a model’s parameters