Skip to main content

​
Indexes

In Pinecone, you store data in an index, typically one per use case. Every index is defined by a schema that declares its fields. What the schema can hold, and which API reads and writes the index, is set when you create it. There are two kinds: new indexes are document indexes by default, and vector indexes remain fully supported.

​
Document index

You define a schema with pc.indexes.create (or POST /indexes).
  • One schema can combine dense_vector, sparse_vector, and full_text_search-enabled string fields.
  • A single index can serve full-text search (BM25 with Lucene queries), semantic search, and sparse-vector search together, often covering what previously required two indexes.
  • Holds documents, read and written through the Documents API. Pick the ranking signal per query with score_by.

​
Vector index

Created with pc.create_index(dimension=..., metric=..., vector_type=...). You don’t declare fields yourself; the SDK builds the schema from the dimension, metric, and vector type you provide.
As of API version 2026-07, POST /indexes in the REST API is schema-only. The SDKs still accept dimension, metric, and vector_type and create a vector index. Existing indexes keep working unchanged on the API they were created with. See Adopt the Documents API for what changed and whether it affects your code.

​
Search approaches

How you rank results depends on the fields your index declares.

​
Full-text search

Full-text search is BM25 token matching with Lucene query syntax over text fields in your schema, string fields you’ve declared with full_text_search enabled. No model required: Pinecone handles tokenization, IDF, and length normalization at index time and BM25 scoring at query time. When you search, you rank results via score_by: text (BM25), query_string (Lucene), dense_vector, or sparse_vector. All scoring methods can be combined with metadata filters, including the text match operators ($match_phrase, $match_all, $match_any) for phrase and token matching. For example:
Reach for full-text search when relevance comes down to specific tokens appearing in both the query and the data, such as SKUs, error messages, code, and named entities. For semantic similarity over natural-language queries, see Semantic search. For retrieval with a learned sparse encoder, see Sparse-vector search. Learn more: A dense vector encodes the meaning of text, images, or other data as a fixed-length list of numbers. Items with similar meaning sit close to each other in vector space, and a query returns the records closest to the query vector. This is semantic search (also called nearest neighbor search, similarity search, or vector search). For the underlying concept, see Dense vector. Learn more: A sparse vector represents tokens (or token-like features) and their weights, with the vast majority of dimensions zero. A query returns records that share the most weighted tokens with the query vector, which is called sparse-vector search. Sparse vectors come from a sparse embedding model. Pinecone hosts pinecone-sparse-english-v0; you can also bring your own. For the underlying concept and the distinction from full-text search, see Index with sparse vectors. Learn more:

​
Limitations

Indexes of sparse vectors have the following limitations:
  • Max non-zero values per sparse vector: 2048
  • Max upserts per second per index of sparse vectors: 10
  • Max queries per second per index of sparse vectors: 100
  • Max top_k value per query: 10,000
    You may get fewer than top_k results if top_k is larger than the number of sparse vectors in your index that match your query. That is, any vectors where the dotproduct score is 0 will be discarded.
  • Max query results size: 4 MB
Semantic search can miss exact keyword matches, while keyword search can miss semantically related results. To get the best of both, use hybrid search — combine a keyword signal (BM25 or sparse) with a dense signal at query time, often with reranking.

​
Namespaces

Within an index, records or documents are partitioned into namespaces, and all upserts, queries, and other data read and write operations always target one namespace. This has two main benefits:
  • Multitenancy: When you need to isolate data between customers, you can use one namespace per customer and target each customer’s writes and queries to their dedicated namespace. See Implement multitenancy for end-to-end guidance.
  • Faster queries: When you divide your data into namespaces in a logical way, you speed up queries by ensuring only relevant records or documents are scanned. The same applies to fetching them, listing their IDs, and other data operations.
Namespaces are created automatically during upsert. If a namespace doesn’t exist, it’s created implicitly.
Namespaces per serverless index vary by plan. On the Standard and Enterprise plans, Pinecone can accommodate million-scale namespaces and beyond for specific use cases. If your application requires more than 100,000 namespaces, contact Support.

​
Vector embedding

A schema declares the vector fields your index uses: a dense vector field, a sparse vector field, or both. Dense vectors represent the semantics of data such as text, images, and audio; sparse vectors capture keyword information. To turn your source data into vectors, you use an embedding model. You can either use Pinecone’s integrated embedding models to convert your data to vectors automatically, or use an external embedding model and bring your own vectors to Pinecone.

​
Integrated embedding

Integrated-embedding indexes are created with pc.create_index_for_model and read and written through the Records API. Pinecone generates the vectors from your text automatically, both when you upsert and when you search.
  1. Create an index that is integrated with one of Pinecone’s hosted embedding models.
  2. Upsert your source text. Pinecone uses the integrated model to convert the text to vectors automatically.
  3. Search with a query text. Again, Pinecone uses the integrated model to convert the text to a vector automatically.
Indexes with integrated embedding do not support updating or importing with text.

​
Bring your own vectors

  1. Use an embedding model to convert your text to vectors. The model can be hosted by Pinecone or an external provider.
  2. Create an index that matches the characteristics of the model.
  3. Upsert your vectors directly.
  4. Use the same external embedding model to convert a query to a vector.
  5. Search with your query vector directly.

​
Data ingestion

To control costs when ingesting large datasets (10,000,000+ records), use import instead of upsert.
There are two ways to ingest data into an index:
  • Importing from object storage is the most efficient and cost-effective way to load large numbers of records or documents into an index. You store your data in object storage (Parquet for vector indexes, JSON Lines (JSONL) for document indexes), integrate your object storage with Pinecone, and then start an asynchronous, long-running operation that imports and indexes your data.
  • Upserting is intended for ongoing writes to an index. Batch upserting can improve throughput performance and is a good option for larger numbers of records or documents (up to 1000 per batch) if you can’t work around import’s current limitations.

​
Metadata

Every record has an ID and a vector, and every document has an _id and the fields its schema declares. Either can also carry metadata: extra key-value fields you filter on at query time. In a vector index, you pass metadata as an explicit object with each vector. With integrated embedding or in a document index, extra fields you upsert are stored as metadata automatically. Pinecone indexes metadata for filtering, so a query can include a metadata filter to limit the search. Searches without a metadata filter don’t consider metadata and search the entire namespace.

​
Metadata format

  • Metadata fields must be key-value pairs in a flat JSON object. Nested JSON objects are not supported.
  • Keys must be strings and must not start with a $.
  • Values must be one of the following data types:
    • String
    • Integer (converted to a 64-bit floating point by Pinecone)
    • Floating point
    • Boolean (true, false)
    • List of strings
  • Null metadata values aren’t supported. Instead of setting a key to null, remove the key from the metadata payload.
Examples

​
Metadata size

Pinecone supports 40 KB of metadata per record or document. full_text_search string fields aren’t metadata and don’t count toward this limit. Each full_text_search string field is limited to 100 KB and 10,000 tokens.

​
Metadata filter expressions

Pinecone’s filtering language supports the following operators:
At the top level, list one or more fields (combined with implicit AND) or combine clauses with the logical operators $and and $or. Use $not to negate a clause, as shown in the table. A bare comparison operator (like $gt) can’t appear at the top level; nest it under a field.
Each $in or $nin operator accepts a maximum of 10,000 values. Exceeding this limit will cause the request to fail. For more information, see Metadata filter limits.
For example, the following has a "genre" metadata field with a list of strings:
JSON
This means "genre" takes on both values, and requests with the following filters will match:
JSON
However, requests with the following filter will not match:
JSON
Additionally, requests with the following filters will not match because they are invalid. They will result in a compilation error:
JSON
JSON