Skip to main content
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.
  • embed takes a hosted dense model (default llama-text-embed-v2) and optional dimension, metric, and write_parameters/read_parameters (model parameters applied when embedding on write and on query, such as truncate).
  • 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).
For available models and their supported dimensions, see the model guide. 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

​
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 its first N tokens (507 for multilingual-e5-large, 2,048 for llama-text-embed-v2, 512 by default for pinecone-sparse-english-v0). 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.

​
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 upsert or update that embeds text reports the tokens it consumed as usage.embed_total_tokens.
You can’t bulk import into an index with an embed or sparse_embed field. Add text through upsert or update instead.
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.
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.