# Agentic IDEs and CLIs Source: https://docs.pinecone.io/guides/get-started/ai-coding-tools Use Pinecone with agentic IDEs and CLIs like Claude Code, Gemini CLI, and Cursor via MCP server, plugins, and agent skills for vector search. Pinecone provides official plugins, extensions, and agent skills for agentic IDEs and CLIs. Use the Pinecone [MCP server](/guides/operations/mcp-server) (Model Context Protocol) and built-in skills to manage vector database indexes, run semantic search, and build RAG applications — all through natural language in your development environment. For direct, scriptable access from the same terminal, the [Pinecone CLI](/reference/cli/quickstart) (`pc`) lets you manage indexes, namespaces, and records without an agent in the loop. ## Choose your tool Official Pinecone plugin for Claude Code with skills, MCP tools, and slash commands. Official Pinecone extension for Gemini CLI with skills and MCP tools. Official Pinecone plugin for Cursor with skills, MCP tools, and slash commands. Universal skills library for GitHub Copilot, Codex, and other agentic IDEs. Connect any MCP-compatible client to Pinecone for index management and search. Direct terminal access to Pinecone — manage indexes, namespaces, and records with `pc` commands. ## Which tool should I use? | If you use... | Install... | Command | | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------- | | [Claude Code](https://claude.ai/code) | [Pinecone plugin for Claude Code](/integrations/claude-code) | `claude plugin install pinecone` | | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | [Pinecone Gemini CLI extension](/integrations/gemini-cli) | `gemini extensions install https://github.com/pinecone-io/gemini-cli-extension` | | [Cursor](https://www.cursor.com/) | [Pinecone Cursor plugin](/integrations/cursor) | `/add-plugin pinecone` | | [GitHub Copilot](https://github.com/features/copilot), [Codex](https://chatgpt.com/codex), or another agentic IDE | [Pinecone Agent Skills](/integrations/agent-skills) | `npx skills add pinecone-io/skills` | | Claude Desktop, Antigravity, or another MCP client | [Pinecone MCP server](/guides/operations/mcp-server) | See [MCP server setup](/guides/operations/mcp-server) | | Your terminal directly (no agent) | [Pinecone CLI](/reference/cli/quickstart) | `brew install pinecone-io/tap/pinecone` | All tools require a [Pinecone API key](https://app.pinecone.io/organizations/-/keys). Sign up for a free account at [app.pinecone.io](https://app.pinecone.io). ## What's included Each tool provides access to the following Pinecone skills: | Skill | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **quickstart** | Step-by-step onboarding — create an index, upload data, and run your first search. | | **query** | Search integrated indexes using natural language text via the Pinecone MCP. | | **assistant** | Create, manage, and chat with Pinecone Assistants for document Q\&A with citations. | | **cli** | Use the Pinecone CLI for terminal-based index and vector management. | | **full-text-search** | Create, ingest into, and query a Pinecone full-text-search (FTS) index using the preview API. | | **n8n** | Build [n8n](/integrations/n8n) workflows with the Pinecone Assistant node or Pinecone Vector Store, including best practices and full workflow JSON generation. | | **mcp** | Reference for all available Pinecone MCP server tools and their parameters. | | **pinecone-docs** | Curated links to official Pinecone documentation, organized by topic. | | **help** | Overview of all skills and what you need to get started. | In addition, the [Pinecone MCP server](/guides/operations/mcp-server) provides tools for listing indexes, creating indexes, upserting records, searching, reranking, and more. # Concepts Source: https://docs.pinecone.io/guides/get-started/concepts Learn core Pinecone concepts (organizations, projects, indexes, documents, namespaces, dense and sparse vectors) and how they relate. ## Organization An organization is a group of one or more [projects](#project) that use the same billing. Organizations allow one or more [users](#user) to control billing and permissions for all of the projects belonging to the organization. For more information, see [Understanding organizations](/guides/organizations/understanding-organizations). ## Project A project belongs to an [organization](#organization) and contains one or more [indexes](#index). Each project belongs to exactly one organization, but only [users](#user) who belong to the project can access the indexes in that project. [API keys](#api-key) and [Assistants](#assistant) are project-specific. For more information, see [Understanding projects](/guides/projects/understanding-projects). ## Index Pinecone [serverless indexes](/guides/index-data/indexing-overview) hold your data as [documents](#document) or [records](#record), depending on how the index was created: an index created with a document schema holds documents, while an index created with a dense or sparse vector type holds records. A document is a JSON object with ranking fields that Pinecone indexes according to a schema you define, plus any number of metadata fields. A single index with a document schema can mix multiple ranking field types: a `dense_vector` field for [semantic search](#index-with-dense-vectors), a `sparse_vector` field for [sparse-vector retrieval](#index-with-sparse-vectors), and one or more `string` fields with `full_text_search` enabled for [full-text search](#full-text-search) with BM25 and Lucene queries. Metadata fields (anything else you upsert) are auto-indexed for filtering at upsert time, no schema declaration required. One index per use case is the typical pattern. Because a document can combine vectors, text, and metadata in the same record, a single index often covers what previously required two — pick the ranking signal per query with `score_by`. ### 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` so their content is indexed for token-level retrieval. "Text field" is the colloquial name; the JSON `type` is `string`. No model required — Pinecone handles tokenization, IDF, and length normalization at index time and BM25 scoring at query time. "Token" here means a unit produced by Pinecone's text analyzer (whitespace + punctuation split, lowercased, optionally stemmed) — not the subword unit a dense or sparse embedding model uses internally. See [Tokens and analyzers](/guides/search/full-text-search#tokens-and-analyzers) for the full pipeline. How it works: 1. You upsert data as JSON [documents](#document). 2. You declare each ranking field's type in the index schema: `dense_vector`, `sparse_vector`, or `string` with `full_text_search` (indexed for BM25 ranking and Lucene queries). Metadata fields are not declared in the schema. 3. Pinecone indexes each ranking field according to its declared type and auto-indexes any other fields on the document for metadata filtering. When you search, you choose a scoring method via `score_by`. The literal value of `type` selects the method: `text` (BM25 token matching on a single text field), `query_string` ([Lucene query syntax](/guides/search/full-text-search#query-syntax-reference) across one or more text fields, including cross-field boolean queries), `dense_vector` (vector similarity), or `sparse_vector` (sparse-vector similarity). Any scoring method can be combined with metadata filters — including logical operators (`$and`, `$or`, `$not`), existence checks (`$exists`), and the text-match operators (`$match_phrase`, `$match_all`, `$match_any`) for phrase and token matching against text fields. Use full-text search for keyword and phrase search over text content — product names, identifiers, technical terms, code, and other cases where queries and documents share specific tokens. For sparse-vector retrieval with a learned encoder (such as [`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0)), see [Index with sparse vectors](#index-with-sparse-vectors). For semantic similarity over natural-language queries, see [Index with dense vectors](#index-with-dense-vectors). Learn more: * [Full-text search](/guides/search/full-text-search) * [Document](#document) ### Index with dense vectors These indexes store records that each have one [dense vector](#dense-vector). A dense vector is a series of numbers that represent the meaning and relationships of text, images, or other data. Each vector is a point in a multidimensional space; each number is a coordinate in that space. Vectors that are closer together in that space are semantically similar. When you query an index with dense vectors, Pinecone retrieves records whose vectors are most semantically similar to the query. This is often called **semantic search**, nearest neighbor search, similarity search, or just vector search. If records in an index with dense vectors also have a [sparse vector](#sparse-vector), the index supports single-index [hybrid search](/guides/search/hybrid-search#use-a-single-index-for-dense-and-sparse-vectors) on the same records. This single-index pattern uses the vector API and isn't available for indexes with document schemas. To combine a lexical signal with a dense signal in an index with a document schema, restrict a dense search with a text-match filter or run separate searches and merge the results client-side; see [Hybrid search](/guides/search/hybrid-search). ### Index with sparse vectors These indexes store records that each have one [sparse vector](#sparse-vector) — a vector with very high dimensionality but only a small number of non-zero values. Each dimension typically corresponds to a token in a vocabulary; the non-zero values represent the importance of those tokens in a document. When you search an index with sparse vectors, Pinecone retrieves records whose vectors share the most weighted tokens with the query vector. This is often called **sparse-vector retrieval** or **sparse-vector lexical search**. Sparse vectors are produced by a sparse embedding model. Pinecone hosts [`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0), a learned-sparse encoder that predicts per-token weights and includes term expansion (related concepts that don't appear in the source text). You can also bring your own sparse model. **Sparse-vector lexical search vs. full-text search.** Both retrieve documents using token-level signals over an inverted index. They differ in how tokens are weighted: [full-text search](#full-text-search) uses **BM25** — a statistical scoring function with no machine learning, computed at query time over your raw text fields. Sparse-vector lexical search uses a **learned sparse encoder** that produces token weights at index time, often with term expansion. Use full-text search when you want a strong baseline with no model to manage; use sparse vectors when a learned encoder (yours or Pinecone's hosted one) better captures your domain's term importance and synonyms. A useful gradient: dense ranks on **concept** (semantic similarity), full-text search ranks on **strict character-level token matching** (BM25), and sparse-vector lexical search sits **between them** — token-aware, but with learned per-token weights and term expansion. Sparse vectors carry no positional information, so phrase matching (`"machine learning"` as a contiguous span) requires full-text search, not sparse. ## Namespace A namespace is a partition within an index. It divides [records](#record) into separate groups so that each query scans only one namespace (faster lookups) and each customer's data can be isolated from another customer's (multitenant isolation). All [upserts](/guides/index-data/upsert-data), [queries](/guides/search/search-overview), and other data read and write operations always target one namespace: For more information, see [Use namespaces](/guides/index-data/indexing-overview#namespaces). ## Record A record is the unit of data for [indexes with dense vectors](#index-with-dense-vectors) and [indexes with sparse vectors](#index-with-sparse-vectors): a [record ID](#record-id), one vector (or both vector types for single-index [hybrid search](/guides/search/hybrid-search)), and optional [metadata](#metadata). With [integrated embedding](/guides/index-data/indexing-overview#integrated-embedding) you can upsert raw text instead of a vector, and Pinecone embeds it at index time. When an item has more than one searchable field — say, a text field ranked by BM25 alongside a `dense_vector` field for similarity — model it as a [document](#document). For more information, see [Upsert data](/guides/index-data/upsert-data). ## Document A document is the unit of data in an index with a document schema — a JSON object with a required `_id` field, the ranking fields declared in the index's schema, and any number of metadata fields. Documents support multiple ranking field types in a single record: a `dense_vector` field (for [semantic search](#index-with-dense-vectors)), a `sparse_vector` field (for [sparse-vector retrieval](#index-with-sparse-vectors)), and one or more `string` fields with `full_text_search` enabled (for [full-text search](#full-text-search)). A single document can carry vectors, text, and metadata together, and you choose the scoring method per query via `score_by`. Documents are the recommended shape for new multi-field and full-text workloads; vector-only indexes continue to use [records](#record). Both APIs are fully supported. Document fields can hold structured values: a metadata `string_list` field holds an array of strings; a `dense_vector` field holds an array of floats; a `sparse_vector` field is an object with two parallel arrays — `indices` (token positions) and `values` (token weights). A schema can declare up to 100 `string` fields with `full_text_search` enabled, but at most one `dense_vector` field and at most one `sparse_vector` field per index. Metadata fields are not declared in the schema. Any field on an upserted document that is not declared in the schema is stored, returned via `include_fields`, and automatically indexed for filtering. Pinecone infers metadata field types (string, number, boolean, array of strings) from the values you upsert. Field names must be unique, non-empty strings, must not start with `_` (reserved for system-managed fields like `_id` and `_score`) or `$` (reserved for filter operators), and are limited to 64 bytes. For more information, see [Full-text search](/guides/search/full-text-search). ### Record ID A record ID is a record's unique ID. [Use ID prefixes](/guides/index-data/data-modeling#use-structured-ids) that reflect the type of data you're storing. ### Dense vector A dense vector, also referred to as a vector embedding or simply a vector, is a series of numbers that represent the meaning and relationships of data. Each vector is a point in a multidimensional space; each number is a coordinate in that space. Vectors that are closer together in that space are semantically similar. Dense vectors are stored in indexes (see [Index with dense vectors](#index-with-dense-vectors)). You use a dense embedding model to convert data to dense vectors. The embedding model can be external to Pinecone or [hosted on Pinecone infrastructure](/guides/index-data/create-an-index#embedding-models) and integrated with an index. For more information about dense vectors, see [What are vector embeddings?](https://www.pinecone.io/learn/vector-embeddings/). ### Sparse vector Sparse vectors are often used to represent documents or queries in a way that captures keyword information. Each dimension in a sparse vector typically represents a word from a dictionary, and the non-zero values represent the importance of these words in the document. Sparse vectors have a large number of dimensions, but a small number of those values are non-zero. Because most values are zero, Pinecone stores sparse vectors efficiently by keeping only the non-zero values along with their corresponding indices. Sparse vectors are stored in indexes (see [Index with sparse vectors](#index-with-sparse-vectors)) and can also coexist with dense vectors in a single index for [hybrid search](/guides/search/hybrid-search#use-a-single-index-for-dense-and-sparse-vectors) on the vector API. To combine a lexical signal with a dense signal in an index with a document schema, restrict a dense search with a text-match filter on a `string` field with `full_text_search` enabled or run separate searches and merge the results client-side. To convert data to sparse vectors, use a sparse embedding model. The embedding model can be external to Pinecone or [hosted on Pinecone infrastructure](/guides/index-data/create-an-index#embedding-models) and integrated with an index. For more information about sparse vectors, see [Sparse retrieval](https://www.pinecone.io/learn/sparse-retrieval/). ### Metadata Metadata is additional information included in a record to provide more context and enable additional [filtering capabilities](/guides/index-data/indexing-overview#metadata). For example, the original text that was embedded can be stored in the metadata. ## Other concepts Although not represented in the diagram above, Pinecone also contains the following concepts: * [API key](#api-key) * [User](#user) * [Backup or collection](#backup-or-collection) * [Pinecone Inference](#pinecone-inference) * [Read unit (RU)](#read-unit-ru) * [Write unit (WU)](#write-unit-wu) ### API key An API key is a unique token that [authenticates](/reference/api/authentication) and authorizes access to the [Pinecone APIs](/reference/api/introduction). API keys are project-specific. ### User A user is a member of organizations and projects. Users are assigned specific roles at the organization and project levels that determine the user's permissions in the [Pinecone console](https://app.pinecone.io). For more information, see [Manage organization members](/guides/organizations/manage-organization-members) and [Manage project members](/guides/projects/manage-project-members). ### Backup or collection A backup is a static copy of a serverless index. Backups only consume storage. They are non-queryable representations of a set of records. You can create a backup from an index, and you can create a new index from that backup. The new index configuration can differ from the original source index: for example, it can have a different name. However, it must have the same number of dimensions and similarity metric as the source index. For more information, see [Understanding backups](/guides/manage-data/backups-overview). ### Pinecone Inference Pinecone Inference is an API service that provides access to [embedding models](/guides/index-data/create-an-index#embedding-models) and [reranking models](/guides/search/rerank-results#reranking-models) hosted on Pinecone's infrastructure. ### Read unit (RU) A read unit (RU) is the unit Pinecone uses to measure and price the cost of read requests to a serverless index, including [query](/guides/manage-cost/understanding-cost#query), [fetch](/guides/manage-cost/understanding-cost#fetch), and [list](/guides/manage-cost/understanding-cost#list). For how read units are calculated, see [Understanding cost](/guides/manage-cost/understanding-cost#read-units). ### Write unit (WU) A write unit (WU) is the unit Pinecone uses to measure and price the cost of write requests to a serverless index, including [upsert](/guides/manage-cost/understanding-cost#upsert), [update](/guides/manage-cost/understanding-cost#update), and [delete](/guides/manage-cost/understanding-cost#delete). For how write units are calculated, see [Understanding cost](/guides/manage-cost/understanding-cost#write-units). ## Learn more * [Vector database](https://www.pinecone.io/learn/vector-database/) * [Pinecone APIs](/reference/api/introduction) * [Approximate nearest neighbor (ANN) algorithms](https://www.pinecone.io/learn/a-developers-guide-to-ann-algorithms/) * [Retrieval augmented generation (RAG)](https://www.pinecone.io/learn/retrieval-augmented-generation/) * [Image search](https://www.pinecone.io/learn/series/image-search/) * [Tokenization](https://www.pinecone.io/learn/tokenization/) # Architecture Source: https://docs.pinecone.io/guides/get-started/database-architecture Learn how Pinecone's serverless architecture (API gateway, control plane, data plane, and object storage) powers vector search at scale. ## Overview Pinecone runs as a managed service on AWS, GCP, and Azure cloud platforms. When you send a request to Pinecone, it goes through an [API gateway](#api-gateway) that routes it to either a global [control plane](#control-plane) or a regional [data plane](#data-plane). All your vector data is stored in highly efficient, distributed [object storage](#object-storage). ### API gateway Every request to Pinecone includes an [API key](/guides/projects/manage-api-keys) that's assigned to a specific [project](/guides/projects/understanding-projects). The API gateway first validates your API key to make sure you have permission to access the project. Once validated, it routes your request to either the global control plane (for managing projects and indexes) or a regional data plane (for reading and writing data), depending on what you're trying to do. ### Control plane The global control plane manages your organizational resources like projects and indexes. It uses a dedicated database to keep track of all these objects. The control plane also handles billing, user management, and coordinates operations across different regions. ### Data plane The data plane handles all requests to write and read records in [indexes](/guides/index-data/indexing-overview) within a specific [cloud region](/guides/index-data/create-an-index#cloud-regions). Each index is divided into one or more logical [namespaces](/guides/index-data/indexing-overview#namespaces), and all your data read and write requests target a specific namespace. Pinecone separates write and read operations into different paths, with each scaling independently based on demand. This separation ensures that your queries never slow down your writes, and your writes never slow down your queries. ### Object storage For each namespace in a serverless index, Pinecone organizes records into immutable files called slabs. These slabs are [optimized for fast querying](#index-builder) and stored in distributed object storage that provides virtually unlimited scalability and high availability. ## Write path ### Request log When you send a write request (to add, update, or delete records), the [data plane](#data-plane) first logs the request details with a unique sequence number (LSN). This ensures all operations happen in the correct order and provides a way to track the state of the index. Pinecone immediately returns a `200 OK` response, guaranteeing that your write is durable and won't be lost. The system then processes your write in the background. ### Index builder The index builder stores your write data in an in-memory structure called a memtable. This includes your vector data, any metadata you've attached, and the sequence number. If you're updating or deleting a record, the system also tracks how to handle the old version during queries. Periodically, the index builder moves data from the memtable to permanent storage. In [object storage](#object-storage), your data is organized into immutable files called slabs. These slabs are optimized for query performance. Smaller slabs use fast indexing techniques that provide good performance with minimal resource requirements. As slabs grow, the system merges them into larger slabs that use more sophisticated methods that provide better performance at scale. This adaptive process both optimizes query performance for each slab and amortizes the cost of more expensive indexing through the lifetime of the namespace. All read operations check the memtable first, so you can immediately search data that you've just written, even before it's moved to permanent storage. For more details, see [Query executors](#query-executors). ## Read path ### Query routers When you send a search query, the [data plane](#data-plane) first validates your request and checks that it meets system limits like [rate and object limits](/reference/api/database-limits). The query router then identifies which slabs contain relevant data and routes your query to the appropriate executors. It also searches the memtable for any recent data that hasn't been moved to permanent storage yet. ### Query executors Each query executor searches through its assigned slabs and returns the most relevant candidates to the query router. If your query includes metadata filters, the executors exclude records that don't match your criteria before finding the best matches. Most of the time, the slabs are cached in memory or on local SSD, which provides very fast query performance. If a slab isn't cached (which happens when it's accessed for the first time or hasn't been used recently), the executor fetches it from object storage and caches it for future queries. The query router then combines results from all executors, removes duplicates, merges them with results from the memtable, and returns the final set of best matches to you. # Pinecone documentation Source: https://docs.pinecone.io/guides/get-started/overview Pinecone is the vector database for AI agents and applications, built for semantic search, knowledge retrieval, and long-term memory at scale. ## Get started Build semantic search and knowledge retrieval into your agent or app Create an AI assistant that answers questions about your proprietary data Compile your data into a context and query it for grounded, cited answers Publish a no-code knowledge app from a template (public preview) ## Build Use Pinecone with Claude Code, Gemini CLI, Cursor, and other agentic tools Connect any MCP-compatible agent to Pinecone for search and index management Comprehensive details about the Pinecone APIs, SDKs, and architecture Notebooks and sample apps with common AI patterns Third-party integrations for LangChain, LlamaIndex, and more What's new in Pinecone # Quickstart Source: https://docs.pinecone.io/guides/get-started/quickstart Add Pinecone to your AI agent or app in minutes. Build a knowledge retrieval agent, use your IDE assistant, or integrate the SDK directly. Get Pinecone running in your agent or app. Install the Pinecone plugin for your AI coding tool to get started instantly, or follow a step-by-step path below. ## Agent / LLM? Start here If you're an AI agent or LLM reading this page to generate Pinecone code, here's the full working pattern as a single runnable script. ```python theme={null} import time from pinecone import Pinecone pc = Pinecone(api_key="{{YOUR_API_KEY}}") # Use create_index_for_model, not the dimension-based create_index if not pc.has_index("quickstart"): pc.create_index_for_model( name="quickstart", cloud="aws", region="us-east-1", embed={ "model": "llama-text-embed-v2", "field_map": {"text": "content"} } ) index = pc.Index("quickstart") # Use upsert_records, not upsert(); keyword args required in SDK v9+; each record needs _id + the field_map field index.upsert_records( namespace="docs", records=[ {"_id": "rec1", "content": "Refund requests must be submitted within 30 days.", "category": "policy"}, {"_id": "rec2", "content": "Enterprise support responds within 4 hours.", "category": "policy"}, {"_id": "rec3", "content": "New employees receive 15 days PTO in year one.", "category": "hr"}, {"_id": "rec4", "content": "Production deployments require team lead approval.", "category": "ops"}, {"_id": "rec5", "content": "API rate limit: 1000 requests/minute on Pro tier.", "category": "specs"}, ] ) time.sleep(5) # records take a few seconds to become searchable # Use search() with inputs, not query() with vector= results = index.search( namespace="docs", query={"top_k": 5, "inputs": {"text": "what is the refund policy"}}, rerank={ "model": "bge-reranker-v2-m3", "top_n": 3, "rank_fields": ["content"] } ) for hit in results["result"]["hits"]: print(f"{hit.score:.2f} {hit.fields['content']}") ``` *** ## Get set up To get started, you'll need a Pinecone account and API key. ### 1. Create a Pinecone account If you're new to Pinecone, sign up at [app.pinecone.io](https://app.pinecone.io) and choose a plan: * [Starter plan](https://pinecone.io/pricing/) (free): Free access to most features, but you're limited to one cloud region and need to stay under Starter plan [limits](/reference/api/database-limits). * [Builder plan](https://pinecone.io/pricing/) (\$20/month): Higher quotas than Starter and predictable flat pricing with no usage overages, plus the ability to create indexes in any supported cloud region. Ideal for small production apps. * [Standard plan trial](/guides/organizations/manage-billing/standard-trial): 21 days and \$300 in credits with access to Standard plan [features](https://www.pinecone.io/pricing/) and [higher limits](/reference/api/database-limits) that let you test Pinecone at scale. If you're already on a Starter plan, you can [upgrade to Builder](/guides/organizations/manage-billing/upgrade-billing-plan) at any time, or activate a Standard plan trial (one trial per organization). After signing up, you'll receive an API key in the console. Save this key. You'll need it to authenticate your requests to Pinecone. ### 2. Get a Pinecone API key Create a new API key in the [Pinecone console](https://app.pinecone.io/organizations/-/keys), or use the widget below to generate a key. If you don't have a Pinecone account, the widget will sign you up for the free [Starter plan](https://www.pinecone.io/pricing/).
Your generated API key: ```shell theme={null} "{{YOUR_API_KEY}}" ``` ## Fastest: use your AI coding tool Install the Pinecone plugin for your AI coding tool, then run the quickstart command. The plugin gives your agent up-to-date Pinecone API references, skills, and a bundled MCP server. The quickstart command walks you through setup with the official [Pinecone CLI](/reference/cli/quickstart) before generating and running sample code, so you end up with a reproducible setup instead of pasted snippets. Set your API key, then install the [Pinecone plugin for Claude Code](/integrations/claude-code): ```shell theme={null} export PINECONE_API_KEY="{{YOUR_API_KEY}}" claude plugin install pinecone ``` Start Claude Code and run the quickstart command: ```text theme={null} /pinecone:quickstart ``` The plugin also includes other slash commands, such as `/pinecone:query`, for interactively querying your indexes. Add your Pinecone API key to a `.env` file at your workspace root: ```text theme={null} PINECONE_API_KEY={{YOUR_API_KEY}} ``` Install the [Pinecone plugin for Cursor](/integrations/cursor) from the [Cursor Marketplace](https://cursor.com/marketplace/pinecone), or in Cursor chat run: ```text theme={null} /add-plugin pinecone ``` Then run the quickstart command in Cursor Agent chat: ```text theme={null} /pinecone-quickstart ``` Install [Pinecone Agent Skills](/integrations/agent-skills), then ask your agent to get started: ```bash theme={null} npx skills add pinecone-io/skills ``` ```text theme={null} Help me get started with Pinecone. Create a serverless index with integrated embedding, upsert some sample data, and run a search. ``` To drive the same setup yourself without an AI tool, use the [Pinecone CLI](/reference/cli/quickstart) directly. For full MCP server setup (index management, search, and docs access from your IDE), see [Use the Pinecone MCP server](/guides/operations/mcp-server). ## Choose your path **Records or documents?** There are two ways to model data in Pinecone, and the choice is made when you create the index. An index created with a dense or sparse vector type holds [records](/guides/get-started/concepts#record), the path the steps below follow using integrated embedding (`create_index_for_model` + `upsert_records` + `search`). An index created with a document schema holds [documents](/guides/get-started/concepts#document) and supports [full-text search](/guides/search/full-text-search) with BM25 ranking and Lucene queries (public preview, with REST and Python SDK support). If keyword and phrase matching matters to your search, or you need more than one ranking signal in a single index, start from [full-text search](/guides/search/full-text-search) instead. To compare the two models, see [Data modeling](/guides/index-data/data-modeling). Build a knowledge retrieval agent with Pinecone as a tool. \~80 lines of Python. Let Claude Code, Cursor, or Gemini CLI build it for you. Integrate Pinecone directly with Python, JavaScript, Java, or Go. Build a workflow in n8n without writing code. *** ## Build a knowledge retrieval agent Build an AI agent that uses Pinecone to retrieve knowledge and answer questions accurately. This demo shows Pinecone as a tool inside an agent, which is the same pattern you'd use in production. This path requires an [Anthropic](https://console.anthropic.com/) or [OpenAI](https://platform.openai.com/api-keys) API key alongside your Pinecone API key. If you don't have one, try the [IDE assistant](#fastest-use-your-ai-coding-tool) or [SDK](#integrate-the-sdk-directly) path instead. ```bash Anthropic (Claude) theme={null} pip install pinecone anthropic ``` ```bash OpenAI theme={null} pip install pinecone openai ``` Create a Pinecone index with [integrated embedding](/guides/index-data/indexing-overview#integrated-embedding) and load a small knowledge base. These are facts your LLM doesn't know on its own, so retrieval is the only way to answer accurately. ```python Anthropic (Claude) theme={null} import anthropic from pinecone import Pinecone pc = Pinecone(api_key="{{YOUR_API_KEY}}") llm = anthropic.Anthropic(api_key="YOUR_ANTHROPIC_API_KEY") # Create an index with integrated embedding if not pc.has_index("knowledge"): pc.create_index_for_model( name="knowledge", cloud="aws", region="us-east-1", embed={ "model": "llama-text-embed-v2", "field_map": {"text": "content"} } ) index = pc.Index("knowledge") # Load your knowledge base index.upsert_records( namespace="docs", records=[ {"_id": "policy-1", "content": "Refund requests must be submitted within 30 days of purchase. After 30 days, only store credit is available.", "category": "policies"}, {"_id": "policy-2", "content": "Enterprise customers get dedicated support with a 4-hour response time SLA. Standard support responds within 24 hours.", "category": "policies"}, {"_id": "spec-1", "content": "The WonderVector 5000 supports up to 100,000 vectors per namespace with a maximum dimensionality of 4096.", "category": "specs"}, {"_id": "spec-2", "content": "API rate limits: Free tier is 100 requests/minute, Pro tier is 1000 requests/minute, Enterprise is unlimited with fair use.", "category": "specs"}, {"_id": "spec-3", "content": "Data is encrypted at rest using AES-256 and in transit using TLS 1.3. SOC2 Type II compliance is maintained.", "category": "security"}, {"_id": "hr-1", "content": "New employees receive 15 days PTO in their first year, increasing to 20 days after 2 years and 25 days after 5 years.", "category": "hr"}, {"_id": "hr-2", "content": "The company matches 401k contributions up to 4% of salary. Vesting is immediate for all employees.", "category": "hr"}, {"_id": "proc-1", "content": "To request a new software license, submit a ticket in the IT portal. Approvals take 2-3 business days for standard software.", "category": "procedures"}, {"_id": "proc-2", "content": "Production deployments require approval from the team lead and a passing CI/CD pipeline. Hotfixes can bypass the lead approval.", "category": "procedures"}, {"_id": "proc-3", "content": "Vendor invoices over $10,000 require VP approval. Under $10,000 requires manager approval only.", "category": "procedures"}, ] ) ``` ```python OpenAI theme={null} from openai import OpenAI from pinecone import Pinecone pc = Pinecone(api_key="{{YOUR_API_KEY}}") llm = OpenAI(api_key="YOUR_OPENAI_API_KEY") # Create an index with integrated embedding if not pc.has_index("knowledge"): pc.create_index_for_model( name="knowledge", cloud="aws", region="us-east-1", embed={ "model": "llama-text-embed-v2", "field_map": {"text": "content"} } ) index = pc.Index("knowledge") # Load your knowledge base index.upsert_records( namespace="docs", records=[ {"_id": "policy-1", "content": "Refund requests must be submitted within 30 days of purchase. After 30 days, only store credit is available.", "category": "policies"}, {"_id": "policy-2", "content": "Enterprise customers get dedicated support with a 4-hour response time SLA. Standard support responds within 24 hours.", "category": "policies"}, {"_id": "spec-1", "content": "The WonderVector 5000 supports up to 100,000 vectors per namespace with a maximum dimensionality of 4096.", "category": "specs"}, {"_id": "spec-2", "content": "API rate limits: Free tier is 100 requests/minute, Pro tier is 1000 requests/minute, Enterprise is unlimited with fair use.", "category": "specs"}, {"_id": "spec-3", "content": "Data is encrypted at rest using AES-256 and in transit using TLS 1.3. SOC2 Type II compliance is maintained.", "category": "security"}, {"_id": "hr-1", "content": "New employees receive 15 days PTO in their first year, increasing to 20 days after 2 years and 25 days after 5 years.", "category": "hr"}, {"_id": "hr-2", "content": "The company matches 401k contributions up to 4% of salary. Vesting is immediate for all employees.", "category": "hr"}, {"_id": "proc-1", "content": "To request a new software license, submit a ticket in the IT portal. Approvals take 2-3 business days for standard software.", "category": "procedures"}, {"_id": "proc-2", "content": "Production deployments require approval from the team lead and a passing CI/CD pipeline. Hotfixes can bypass the lead approval.", "category": "procedures"}, {"_id": "proc-3", "content": "Vendor invoices over $10,000 require VP approval. Under $10,000 requires manager approval only.", "category": "procedures"}, ] ) ``` Pinecone is eventually consistent. New records may take a few seconds to become searchable. Wrap Pinecone search in a function your agent can call. Drop this into any agent codebase to add knowledge retrieval. Run all snippets in the same Python session so `index` and `llm` stay in scope.
**Agent tool: `search_knowledge_base`** ```python Python theme={null} def search_knowledge_base(query: str) -> str: """Search the knowledge base for relevant information.""" results = index.search( namespace="docs", # To scope by metadata, add "filter": {"category": {"$eq": "policies"}} to the query dict query={"top_k": 3, "inputs": {"text": query}}, rerank={ "model": "bge-reranker-v2-m3", "top_n": 3, "rank_fields": ["content"] } ) return "\n\n".join( hit.fields["content"] for hit in results["result"]["hits"] ) ```
Give your LLM the ability to call the search function when it needs information. ```python Anthropic (Claude) theme={null} tools = [{ "name": "search_knowledge_base", "description": "Search the company knowledge base for policies, specs, HR info, and procedures.", "input_schema": { "type": "object", "properties": { "query": {"type": "string", "description": "The search query"} }, "required": ["query"] } }] def ask(question: str) -> str: messages = [{"role": "user", "content": question}] # disable_parallel_tool_use keeps this loop simple: with parallel calls, # every tool_use block would need a matching tool_result in the next message response = llm.messages.create( model="claude-sonnet-4-5", max_tokens=1024, tools=tools, tool_choice={"type": "auto", "disable_parallel_tool_use": True}, messages=messages ) # If the model wants to use a tool, call it and return the result while response.stop_reason == "tool_use": tool_block = next(b for b in response.content if b.type == "tool_use") tool_result = search_knowledge_base(tool_block.input["query"]) messages += [ {"role": "assistant", "content": response.content}, {"role": "user", "content": [{ "type": "tool_result", "tool_use_id": tool_block.id, "content": tool_result }]} ] response = llm.messages.create( model="claude-sonnet-4-5", max_tokens=1024, tools=tools, tool_choice={"type": "auto", "disable_parallel_tool_use": True}, messages=messages ) return next(b.text for b in response.content if hasattr(b, "text")) ``` ```python OpenAI theme={null} import json tools = [{ "type": "function", "function": { "name": "search_knowledge_base", "description": "Search the company knowledge base for policies, specs, HR info, and procedures.", "parameters": { "type": "object", "properties": { "query": {"type": "string", "description": "The search query"} }, "required": ["query"] } } }] def ask(question: str) -> str: messages = [{"role": "user", "content": question}] # parallel_tool_calls=False keeps this loop simple: with parallel calls, # every tool call would need a matching tool message in the next turn response = llm.chat.completions.create( model="gpt-4o", tools=tools, parallel_tool_calls=False, messages=messages ) # If the model wants to use a tool, call it and return the result while response.choices[0].finish_reason == "tool_calls": tool_call = response.choices[0].message.tool_calls[0] args = json.loads(tool_call.function.arguments) tool_result = search_knowledge_base(args["query"]) messages += [ response.choices[0].message, {"role": "tool", "tool_call_id": tool_call.id, "content": tool_result} ] response = llm.chat.completions.create( model="gpt-4o", tools=tools, parallel_tool_calls=False, messages=messages ) return response.choices[0].message.content ``` ```python theme={null} print(ask("What's the refund policy?")) ``` If the agent says it can't find the information, wait a few seconds and retry. Pinecone is eventually consistent, so freshly upserted records take a moment to become searchable. Your agent searches Pinecone, retrieves the relevant policy, and answers: ```console Output theme={null} Refund requests must be submitted within 30 days of purchase. After that 30-day window, you can still receive store credit but not a direct refund. ``` Try a few more questions: ```python theme={null} print(ask("How much PTO do new employees get?")) print(ask("What approval do I need for a $15,000 vendor invoice?")) ``` **What just happened:** Your LLM received a question, decided it needed more information, and called the `search_knowledge_base` tool. Pinecone returned the most relevant records with reranking, and the LLM synthesized an accurate answer from the retrieved context. Production RAG agents use this same pattern, and the `search_knowledge_base` function works in any agent framework. ### Next steps Add conversation history, streaming, and a web UI Explore semantic, hybrid, and full-text search Model your data for efficient retrieval *** ## Integrate the SDK directly Integrate Pinecone directly into your application. Use these SDK calls wherever your code needs knowledge retrieval, whether that's an agent, a backend service, or a standalone script. To get started in your browser, use the [Quickstart colab notebook](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/pinecone-quickstart.ipynb). ### 1. Install an SDK ```shell Python theme={null} pip install pinecone ``` ```shell JavaScript theme={null} npm install @pinecone-database/pinecone ``` ```shell Java theme={null} # Maven io.pinecone pinecone-client 5.0.0 # Gradle implementation "io.pinecone:pinecone-client:5.0.0" ``` ```shell Go theme={null} go get github.com/pinecone-io/go-pinecone/v4/pinecone ``` ### 2. Create an index Create an [index with integrated embedding](/guides/index-data/create-an-index#create-an-index-for-dense-vectors) so you can upsert and search with text. Pinecone generates the vectors for you. If you prefer to use external embedding models, see [Bring your own vectors](/guides/index-data/indexing-overview#bring-your-own-vectors). ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="{{YOUR_API_KEY}}") index_name = "quickstart-py" if not pc.has_index(index_name): pc.create_index_for_model( name=index_name, cloud="aws", region="us-east-1", embed={ "model":"llama-text-embed-v2", "field_map":{"text": "chunk_text"} } ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: '{{YOUR_API_KEY}}' }); const indexName = 'quickstart-js'; await pc.createIndexForModel({ name: indexName, cloud: 'aws', region: 'us-east-1', embed: { model: 'llama-text-embed-v2', fieldMap: { text: 'chunk_text' }, }, waitUntilReady: true, }); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.ApiException; import org.openapitools.db_control.client.model.CreateIndexForModelRequest; import org.openapitools.db_control.client.model.CreateIndexForModelRequestEmbed; import org.openapitools.db_control.client.model.DeletionProtection; import org.openapitools.db_control.client.model.IndexModel; import org.openapitools.db_data.client.model.SearchRecordsRequestQuery; import org.openapitools.db_data.client.model.SearchRecordsResponse; import io.pinecone.proto.DescribeIndexStatsResponse; import java.util.*; public class Quickstart { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("{{YOUR_API_KEY}}").build(); String indexName = "quickstart-java"; String region = "us-east-1"; HashMap fieldMap = new HashMap<>(); fieldMap.put("text", "chunk_text"); CreateIndexForModelRequestEmbed embed = new CreateIndexForModelRequestEmbed() .model("llama-text-embed-v2") .fieldMap(fieldMap); IndexModel index = pc.createIndexForModel( indexName, CreateIndexForModelRequest.CloudEnum.AWS, region, embed, DeletionProtection.DISABLED, null ); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } indexName := "quickstart-go" index, err := pc.CreateIndexForModel(ctx, &pinecone.CreateIndexForModelRequest{ Name: indexName, Cloud: pinecone.Aws, Region: "us-east-1", Embed: pinecone.CreateIndexForModelEmbed{ Model: "llama-text-embed-v2", FieldMap: map[string]interface{}{"text": "chunk_text"}, }, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", err) } else { fmt.Printf("Successfully created serverless index: %v", index.Name) } } func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } ``` ### 3. Upsert data Load records into your index. Each record has an ID, text content, and optional metadata. Pinecone converts the text to vectors automatically using the integrated embedding model. ```python Python [expandable] theme={null} index = pc.Index(index_name) index.upsert_records( namespace="example-namespace", records=[ {"_id": "rec1", "chunk_text": "The Eiffel Tower was completed in 1889 and stands in Paris, France.", "category": "history"}, {"_id": "rec2", "chunk_text": "Photosynthesis allows plants to convert sunlight into energy.", "category": "science"}, {"_id": "rec3", "chunk_text": "Albert Einstein developed the theory of relativity.", "category": "science"}, {"_id": "rec4", "chunk_text": "The mitochondrion is often called the powerhouse of the cell.", "category": "biology"}, {"_id": "rec5", "chunk_text": "Shakespeare wrote many famous plays, including Hamlet and Macbeth.", "category": "literature"}, {"_id": "rec6", "chunk_text": "The Great Wall of China was built to protect against invasions.", "category": "history"}, {"_id": "rec7", "chunk_text": "The Pyramids of Giza are among the Seven Wonders of the Ancient World.", "category": "history"}, {"_id": "rec8", "chunk_text": "Leonardo da Vinci painted the Mona Lisa.", "category": "art"}, {"_id": "rec9", "chunk_text": "The internet revolutionized communication and information sharing.", "category": "technology"}, {"_id": "rec10", "chunk_text": "Renewable energy sources include wind, solar, and hydroelectric power.", "category": "energy"}, ] ) ``` ```javascript JavaScript [expandable] theme={null} const namespace = pc.index(indexName).namespace("example-namespace"); await namespace.upsertRecords({ records: [ {"_id": "rec1", "chunk_text": "The Eiffel Tower was completed in 1889 and stands in Paris, France.", "category": "history"}, {"_id": "rec2", "chunk_text": "Photosynthesis allows plants to convert sunlight into energy.", "category": "science"}, {"_id": "rec3", "chunk_text": "Albert Einstein developed the theory of relativity.", "category": "science"}, {"_id": "rec4", "chunk_text": "The mitochondrion is often called the powerhouse of the cell.", "category": "biology"}, {"_id": "rec5", "chunk_text": "Shakespeare wrote many famous plays, including Hamlet and Macbeth.", "category": "literature"}, {"_id": "rec6", "chunk_text": "The Great Wall of China was built to protect against invasions.", "category": "history"}, {"_id": "rec7", "chunk_text": "The Pyramids of Giza are among the Seven Wonders of the Ancient World.", "category": "history"}, {"_id": "rec8", "chunk_text": "Leonardo da Vinci painted the Mona Lisa.", "category": "art"}, {"_id": "rec9", "chunk_text": "The internet revolutionized communication and information sharing.", "category": "technology"}, {"_id": "rec10", "chunk_text": "Renewable energy sources include wind, solar, and hydroelectric power.", "category": "energy"}, ] }); ``` ```java Java [expandable] theme={null} // Add to the Quickstart class: Index index = pc.getIndexConnection(indexName); ArrayList> upsertRecords = new ArrayList<>(); String[][] data = { {"rec1", "The Eiffel Tower was completed in 1889 and stands in Paris, France.", "history"}, {"rec2", "Photosynthesis allows plants to convert sunlight into energy.", "science"}, {"rec3", "Albert Einstein developed the theory of relativity.", "science"}, {"rec4", "The mitochondrion is often called the powerhouse of the cell.", "biology"}, {"rec5", "Shakespeare wrote many famous plays, including Hamlet and Macbeth.", "literature"}, {"rec6", "The Great Wall of China was built to protect against invasions.", "history"}, {"rec7", "The Pyramids of Giza are among the Seven Wonders of the Ancient World.", "history"}, {"rec8", "Leonardo da Vinci painted the Mona Lisa.", "art"}, {"rec9", "The internet revolutionized communication and information sharing.", "technology"}, {"rec10", "Renewable energy sources include wind, solar, and hydroelectric power.", "energy"}, }; for (String[] row : data) { HashMap record = new HashMap<>(); record.put("_id", row[0]); record.put("chunk_text", row[1]); record.put("category", row[2]); upsertRecords.add(record); } index.upsertRecords("example-namespace", upsertRecords); ``` ```go Go [expandable] theme={null} // Add to the main function: idxConnection, err := pc.IndexFromName(ctx, indexName) if err != nil { log.Fatalf("Failed to get index connection: %v", err) } records := []pinecone.UpsertRecord{ {Id: "rec1", Fields: map[string]interface{}{"chunk_text": "The Eiffel Tower was completed in 1889 and stands in Paris, France.", "category": "history"}}, {Id: "rec2", Fields: map[string]interface{}{"chunk_text": "Photosynthesis allows plants to convert sunlight into energy.", "category": "science"}}, {Id: "rec3", Fields: map[string]interface{}{"chunk_text": "Albert Einstein developed the theory of relativity.", "category": "science"}}, {Id: "rec4", Fields: map[string]interface{}{"chunk_text": "The mitochondrion is often called the powerhouse of the cell.", "category": "biology"}}, {Id: "rec5", Fields: map[string]interface{}{"chunk_text": "Shakespeare wrote many famous plays, including Hamlet and Macbeth.", "category": "literature"}}, {Id: "rec6", Fields: map[string]interface{}{"chunk_text": "The Great Wall of China was built to protect against invasions.", "category": "history"}}, {Id: "rec7", Fields: map[string]interface{}{"chunk_text": "The Pyramids of Giza are among the Seven Wonders of the Ancient World.", "category": "history"}}, {Id: "rec8", Fields: map[string]interface{}{"chunk_text": "Leonardo da Vinci painted the Mona Lisa.", "category": "art"}}, {Id: "rec9", Fields: map[string]interface{}{"chunk_text": "The internet revolutionized communication and information sharing.", "category": "technology"}}, {Id: "rec10", Fields: map[string]interface{}{"chunk_text": "Renewable energy sources include wind, solar, and hydroelectric power.", "category": "energy"}}, } err = idxConnection.UpsertRecords(ctx, "example-namespace", records) if err != nil { log.Fatalf("Failed to upsert records: %v", err) } ``` Pinecone is eventually consistent. New records may take a few seconds to become searchable. ### 4. Search and rerank Search the index for records semantically similar to a query, then [rerank](/guides/search/rerank-results) for more accurate results. ```python Python theme={null} query = "Famous historical structures and monuments" results = index.search( namespace="example-namespace", query={ "top_k": 10, "inputs": {"text": query} }, rerank={ "model": "bge-reranker-v2-m3", "top_n": 5, "rank_fields": ["chunk_text"] } ) for hit in results["result"]["hits"]: print(f"score: {round(hit.score, 2):<5} | {hit.fields['chunk_text']}") ``` ```console Output theme={null} score: 0.11 | The Eiffel Tower was completed in 1889 and stands in Paris, France. score: 0.06 | The Great Wall of China was built to protect against invasions. score: 0.02 | The Pyramids of Giza are among the Seven Wonders of the Ancient World. score: 0.01 | Leonardo da Vinci painted the Mona Lisa. score: 0.0 | Shakespeare wrote many famous plays, including Hamlet and Macbeth. ``` ```javascript JavaScript theme={null} const query = 'Famous historical structures and monuments'; const results = await namespace.searchRecords({ query: { topK: 10, inputs: { text: query }, }, rerank: { model: 'bge-reranker-v2-m3', topN: 5, rankFields: ['chunk_text'], }, }); results.result.hits.forEach(hit => { console.log(`score: ${hit._score.toFixed(2)}, text: ${hit.fields.chunk_text}`); }); ``` ```java Java theme={null} // Add to the Quickstart class: String query = "Famous historical structures and monuments"; List fields = new ArrayList<>(); fields.add("category"); fields.add("chunk_text"); List rankFields = new ArrayList<>(); rankFields.add("chunk_text"); SearchRecordsRequestRerank rerank = new SearchRecordsRequestRerank() .query(query) .model("bge-reranker-v2-m3") .topN(5) .rankFields(rankFields); SearchRecordsResponse response = index.searchRecordsByText( query, "example-namespace", fields, 10, null, rerank ); System.out.println(response); ``` ```go Go theme={null} // Add to the main function: query := "Famous historical structures and monuments" topN := int32(5) res, err := idxConnection.SearchRecords(ctx, &pinecone.SearchRecordsRequest{ Query: pinecone.SearchRecordsQuery{ TopK: 10, Inputs: &map[string]interface{}{ "text": query, }, }, Rerank: &pinecone.SearchRecordsRerank{ Model: "bge-reranker-v2-m3", TopN: &topN, RankFields: []string{"chunk_text"}, }, }) if err != nil { log.Fatalf("Failed to search records: %v", err) } fmt.Printf(prettifyStruct(res)) ``` ### 5. Clean up When you no longer need the example index, delete it: ```python Python theme={null} pc.delete_index(index_name) ``` ```javascript JavaScript theme={null} await pc.deleteIndex(indexName); ``` ```java Java theme={null} pc.deleteIndex(indexName); ``` ```go Go theme={null} err = pc.DeleteIndex(ctx, indexName) if err != nil { log.Fatalf("Failed to delete index: %v", err) } ``` For production indexes, consider [enabling deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection). ### Next steps Learn more about storing data in Pinecone Explore different forms of vector search Find out how to improve performance *** ## No-code with n8n Create an AI workflow that uses Pinecone for knowledge retrieval without writing any code. Use [n8n](https://docs.n8n.io/choose-n8n/) to create a workflow that downloads files via HTTP and lets you chat with them using Pinecone Database and OpenAI. If you're not interested in chunking and embedding your own data, [use n8n with Pinecone Assistant](/guides/assistant/quickstart/n8n-quickstart) instead. ### 1. Get an OpenAI API key Create a new API key in the [OpenAI console](https://platform.openai.com/api-keys). ### 2. Create an index [Create an index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless) in the Pinecone console: * Name your index `n8n-dense-index` * Under **Configuration**, check **Custom settings** and set **Dimension** to 1536. * Leave everything else as default. ### 3. Set up n8n In your n8n account, [create a new workflow](https://docs.n8n.io/workflows/create/). Copy this workflow template URL: ```shell theme={null} https://raw.githubusercontent.com/pinecone-io/n8n-templates/refs/heads/main/database-quickstart/database-quickstart.json ``` Paste the URL into the workflow editor and then click **Import** to add the workflow. * Add your Pinecone credentials: * In the **Pinecone Vector Store** node, select **Credential to connect with** > **Create new credential** and paste in your Pinecone API key. * Name the credential **Pinecone** so that other nodes reference it. * Add your OpenAI credentials: * In the **OpenAI Chat Model**, select **Credential to connect with** > **Create new credential** and paste in your OpenAI API key. The workflow is configured to download recent Pinecone release notes and upload them to your Pinecone index. Click **Execute workflow** to start the workflow. You can add your own files to the workflow by changing the URLs in the **Set file urls** node. ### 4. Chat with your docs Once the workflow is activated, ask it for the latest changes to Pinecone Database: ``` What's new in Pinecone Database? ``` ### Next steps * Use your own data: * Change the urls in **Set file urls** node to use your own files. * You may need to adjust the chunk sizes in the **Recursive Character Text Splitter** node or use a different chunking strategy. See [Chunking Strategies for LLM Applications](https://www.pinecone.io/learn/chunking-strategies/) for more info. * Customize the system message of the **AI Agent** node to reflect what the **Pinecone Vector Store Tool** will be used for. * Customize the description of the **Pinecone Vector Store Tool** to reflect what data you are storing in the Pinecone index. * Use n8n, Pinecone Assistant, and OpenAI to [chat with your Google Drive documents](https://n8n.io/workflows/9942-rag-powered-document-chat-with-google-drive-openai-and-pinecone-assistant/). * Get help in the [Pinecone Discord community](https://discord.gg/tJ8V62S3sH). # Test Pinecone at scale Source: https://docs.pinecone.io/guides/get-started/test-at-scale Benchmark Pinecone at production scale by importing 10M vectors and measuring semantic search throughput, query latency, and costs. This guide walks you through testing Pinecone at production scale. You'll import 10 million vectors, run a benchmark, and analyze the results to verify Pinecone meets production requirements for semantic search applications. This test requires a Pinecone account on the Standard or Enterprise plan because it uses [import from object storage](/guides/index-data/import-data), which is not available on the Starter or Builder plans. New users can sign up for the [Standard trial](/guides/organizations/manage-billing/standard-trial) for 21 days and \$300 in credits, more than enough to cover the costs of this test. Existing users on the Starter or Builder plan can [upgrade](/guides/organizations/manage-billing/upgrade-billing-plan). ## About this test Semantic search enables finding relevant content based on meaning rather than exact keyword matches, making it ideal for applications like product search, content recommendation, and question-answering systems. This test simulates a production-scale semantic search workload, measuring import time, query throughput, query latency, and associated costs. The test uses the following configuration: * **Records**: 10 million records from the [Amazon Reviews 2023](https://amazon-reviews-2023.github.io/) dataset * **Embedding model**: `llama-text-embed-v2` (1024 dimensions) * **Similarity metric**: cosine * **Total size**: 48.8 GB * **Query load**: 10 queries per second total (across all users) * **Concurrent users**: 10 users querying simultaneously * **Test queries**: 100,000 queries * **Import time target**: \< 30 minutes * **Query latency target**: p90 latency \< 100ms **Estimated cost**: \~\$127 (import: \$48.80, queries: \$78.08, storage: \$0.09) — see [detailed cost breakdown](#6-check-costs) ## 1. Get an API key To follow the steps in this guide, you'll need an API key. Create a new API key in the [Pinecone console](https://app.pinecone.io/organizations/-/keys), or use this widget:
Your generated API key: ```shell theme={null} "{{YOUR_API_KEY}}" ``` ## 2. Create an index This test requires you to use AWS-based indexes and infrastructure. The sample dataset is only available from Amazon S3, and you can only import from Amazon S3 to Pinecone indexes hosted on AWS. To run the benchmark, you'll need to provision an AWS EC2 instance in the same region as your index. Create an on-demand index that matches the dimensions and similarity metric of the dataset you'll import in later steps. 1. In the Pinecone console, go to the [Indexes](https://app.pinecone.io/organizations/-/projects/-/indexes) page. 2. Click **Create index**. 3. Check **Custom settings**. 4. Configure the index with the following settings: * **Name**: `search-10m` * **Vector type**: Dense * **Dimensions**: `1024` * **Metric**: cosine * **Capacity mode**: Serverless (on-demand) * **Cloud**: AWS (required for this test) * **Region**: Use an AWS region appropriate for your use case (for example, `us-east-1`) 5. Click **Create index**. If using code to create an index, first install the [Python SDK](/reference/python-sdk): ```shell Terminal theme={null} pip install pinecone ``` Then, create the index: ```python Python theme={null} from pinecone import Pinecone, ServerlessSpec pc = Pinecone(api_key="{{YOUR_API_KEY}}") index_name = "search-10m" if not pc.has_index(index_name): pc.create_index( name=index_name, vector_type="dense", dimension=1024, metric="cosine", spec=ServerlessSpec( # AWS is required for this test cloud="aws", # Use an AWS region appropriate for your use case region="us-east-1" ) ) ``` ## 3. Import the dataset Pinecone's [import feature](/guides/index-data/import-data) enables you to load millions of vectors from object storage in parallel. In this step, you'll import 10 million records into a single namespace (`ns_2`) in your index. ### Choose an import source To import the dataset, you'll need to use the following Amazon S3 import URL: ``` s3://fe-customer-pocs/search/search_10M/dense/ ``` ### Start and monitor the import For this dataset, the import should take less than 30 minutes. 1. In the Pinecone console, go to the [Indexes](https://app.pinecone.io/organizations/-/projects/-/indexes) page. 2. Find your `search-10m` index and click **... > Import data**. 3. For **Storage integration**, select **No integration (public bucket)**. 4. Enter the import URL: `s3://fe-customer-pocs/search/search_10M/dense/`. 5. For **Error handling**, select **Abort on error (default)**. 6. Click **Start import**. To monitor progress, open your index in the Pinecone console and navigate to the **Imports** tab. After the import completes, compare the **Started time** and **End time** timestamps to see the total time required. For this dataset, the import should take around 30 minutes. While the import is running, you can continue with the next step to provision a VM and install VSB. However, wait for the import to complete before running the benchmark. Start the import: ```python Python theme={null} from pinecone import Pinecone, ImportErrorMode pc = Pinecone(api_key="{{YOUR_API_KEY}}") index = pc.Index("search-10m") import_response = index.start_import( uri="s3://fe-customer-pocs/search/search_10M/dense/", error_mode=ImportErrorMode.ABORT ) print(f"Import started: {import_response['id']}") ``` Monitor import progress: ```python Python theme={null} from pinecone import Pinecone import time pc = Pinecone(api_key="{{YOUR_API_KEY}}") index = pc.Index("search-10m") while True: status = index.describe_import(id="IMPORT_ID") print(f"Status: {status['status']}, Progress: {status['percent_complete']:.1f}%") if status['status'] == "Completed": print("Import completed successfully!") break elif status['status'] == "Failed": print("Import failed. Check error details.") break elif status['status'] == "Cancelled": print("Import cancelled.") break time.sleep(15) # Check every 15 seconds ``` There are three ways to find the import ID: * It's returned when the import is started * In the Pinecone console, on the **Imports** tab for your index * By calling [List imports](/reference/api/latest/data-plane/list_imports) ## 4. Run the benchmark To simulate realistic query patterns and measure latency and throughput for your Pinecone index, use [Vector Search Bench (VSB)](https://github.com/pinecone-io/VSB). The benchmark runs 100,000 queries at 10 queries per second, which should take just under three hours to complete. VSB reports latency as the time from when the tool issues a query to when the query is returned by Pinecone. To minimize the client-side latency between the tool and Pinecone, run the benchmark on a dedicated AWS EC2 instance that's hosted in the same AWS region as your Pinecone index. This reduces the client-side latency to sub-millisecond range. As noted in [section 2](#2-create-an-index), this test requires an AWS EC2 instance in the same region as your index. For instructions on how to provision an EC2 instance, see the [AWS documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/LaunchingAndUsingInstances.html). Create a VM that comes with Python 3.11 or higher. Connect to the VM using SSH or the cloud provider's console. [VSB (Vector Search Bench)](https://github.com/pinecone-io/VSB) is a benchmarking suite for testing vector database search performance across different workloads and databases. To install it, you'll first need to install various dependencies. 1. **Verify Python version** VSB requires Python 3.11 or higher to run. Verify your Python version: ```bash Terminal theme={null} python3 --version ``` If your version is below 3.11, install Python 3.11+ using your distribution's package manager. 2. **Install git** Git is required to clone the VSB repository. Check if git is installed: ```bash Terminal theme={null} git --version ``` If git is not installed, install it using your system's package manager: ```bash Terminal theme={null} # Adapt for your VM's package manager (apt/yum/dnf) sudo apt-get update && sudo apt-get install git ``` 3. **Install pipx** pipx is required to install Poetry. First, check if pip3 is installed: ```bash Terminal theme={null} pip3 --version ``` If pip is not installed, install it using your system's package manager: ```bash Terminal theme={null} # Adapt for your VM's package manager (apt/yum/dnf) sudo apt-get update && sudo apt-get install python3-pip ``` Then check if pipx is installed: ```bash Terminal theme={null} pipx --version ``` If pipx is not installed, install it via your system's package manager: ```bash Terminal theme={null} # Adapt for your VM's package manager (apt/yum/dnf) sudo apt-get update && sudo apt-get install pipx pipx ensurepath ``` After installation, run this command to update the PATH in your current terminal session: ```bash Terminal theme={null} source ~/.bashrc ``` 4. **Install Poetry** [Poetry](https://python-poetry.org/) is required to manage [VSB's](https://github.com/pinecone-io/VSB) Python dependencies and virtual environment. If Poetry is not [installed](https://python-poetry.org/docs/), use pipx to install it: ```bash Terminal theme={null} pipx install poetry ``` Alternatively, use the [official Poetry installer](https://python-poetry.org/docs/#installing-with-the-official-installer). 5. **Clone the VSB repository** To run the benchmark, you'll first need to clone the VSB repository and navigate to it: ```bash Terminal theme={null} git clone https://github.com/pinecone-io/VSB.git cd VSB ``` 6. **Configure Poetry** Since your VM has Python 3.11 or higher installed (as specified in the VM provisioning step), tell Poetry to use it: ```bash Terminal theme={null} poetry env use python3 ``` 7. **Install dependencies** VSB requires several Python packages to run. Install all dependencies: ```bash Terminal theme={null} poetry install ``` To test the performance of your Pinecone index, run the following command from within the `VSB` directory. For more information about VSB, see its [GitHub repository](https://github.com/pinecone-io/VSB). The following command simulates 10 concurrent users issuing a total of 100,000 queries at 10 queries per second (QPS). Each query performs a vector search for the top 10 most similar 1024-dimensional vectors, using cosine similarity, with query vectors selected uniformly at random. The `--skip_populate` flag skips the data population phase, since you've already imported data into your index. ```bash Terminal theme={null} poetry run vsb \ --database="pinecone" \ --workload=synthetic-proportional \ --pinecone_api_key="{{YOUR_API_KEY}}" \ --pinecone_index_name="search-10m" \ --pinecone_namespace_name="ns_2" \ --synthetic_dimensions=1024 \ --synthetic_metric=cosine \ --synthetic_top_k=10 \ --synthetic_requests=100000 \ --users=10 \ --requests_per_sec=10 \ --synthetic_query_distribution=uniform \ --synthetic_query_ratio=1 \ --synthetic_insert_ratio=0 \ --synthetic_delete_ratio=0 \ --synthetic_update_ratio=0 \ --skip_populate ``` ## 5. Analyze performance At the end of the run, VSB prints an operation summary including the requests per second achieved and latencies at different percentiles. Here's an example output: ```shell Terminal theme={null} 2025-12-23T00:34:37 INFO Completed Run phase, took 9940.14s Operation Summary Operation Requests Failures Requests/sec Failures/sec ─────────────────────────────────────────────────────────── Search 99000 0(0%) 10 0.0 Metrics Summary Operation Metric Min 0.1% 1% 5% 10% 25% 50% 75% 90% 95% 99% 99.9% 99.99% Max Mean ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── Search Latency (ms) 23 25 25 26 27 27 29 34 44 81 350 430 1300 4602 43 ``` Confirm that the requests per second achieved is around 10 QPS and the p90 latency is less than 100ms. To see more detailed statistics, you can analyze the `stats.json` file identified in the output. ## 6. Check costs You can check the costs for the import, queries, and storage in the Pinecone console at [Settings > Usage](https://app.pinecone.io/organizations/-/settings/usage). Cost data is delayed up to three days, but once it's available, compare the actual costs to the estimated costs below. For the latest pricing details, see [Pricing](https://www.pinecone.io/pricing). | Cost type | Amount | Pricing | Estimated cost | | :-------- | :-------------- | :--------------------- | :------------- | | Import | 48.8 GB | \$0.25/GB | \$12.20 | | Queries | 100,000 queries | \$16 per 1M read units | \$78.08 | | Storage | 4 hours | \$0.33/GB/month | \$0.09 | | **Total** | | | **\$90.37** | Standard and Enterprise organizations receive a **one-time 1 TB bulk import credit**, valid through August 30, 2026, so on those plans the import portion of this example would be \$0 and the total would be \$78.17. The figures above assume the standard overage rate. The current price for import is \$0.25/GB. The dataset size for this test is 48.8 GB, so the import cost should be \$12.20. A query uses 1 [read unit (RU)](/guides/manage-cost/understanding-cost#read-units) for every 1 GB of namespace size. The current price for queries in the `us-east-1` region of AWS is \$16 per 1 million read units (pricing varies by region). This test ran 100,000 queries against a namespace size of 48.8 GB. Each query uses 48.8 RUs (1 RU per GB), so the total is 4,880,000 RUs. At \$16 per 1 million RUs, the cost is (4,880,000 / 1,000,000) × \$16 = \$78.08. The current price for storage is \$0.33 per GB per month. The dataset size for this test is 48.8 GB. Assuming a total storage time of 4 hours (including import, benchmark runtime, and cleanup), the storage cost is: \$0.33/GB/month \* 48.8 GB / 730 hours \* 4 hours = \$0.09. The total cost for the test is the sum of the import cost, query cost, and storage cost: \$12.20 + \$78.08 + \$0.09 = \$90.37. ## 7. Clean up When you no longer need your test index, [delete it](/guides/manage-data/manage-indexes#delete-an-index) to avoid incurring unnecessary costs. # Check data freshness Source: https://docs.pinecone.io/guides/index-data/check-data-freshness Check data freshness in Pinecone serverless indexes using log sequence numbers (LSNs) and vector counts to verify recent upserts and deletes. Pinecone is eventually consistent, so there can be a slight delay before new or changed records are visible to queries. This page describes two ways of checking the data freshness of a Pinecone index: * To check if a serverless index queries reflect recent writes to the index, [check the log sequence number](#check-the-log-sequence-number). * To check whether an index contains recently inserted or deleted vectors, [verify the number of vectors in the index](#verify-vector-counts). ## Check the log sequence number This method is only available for serverless indexes through the [Database API](https://docs.pinecone.io/reference/api/latest/data-plane/upsert). ### Log sequence numbers When you make a write request to a serverless index namespace, Pinecone assigns a monotonically increasing log sequence number (LSN) to the write operation. The LSN reflects upserts as well as updates and deletes to that namespace. Writes to one namespace do not increase the LSN for other namespaces. You can use LSNs to verify that specific write operations are reflected in your query responses. If the LSN contained in the query response header is greater than or equal to the LSN of the relevant write operation, then that operation is reflected in the query response. If the LSN contained in the query response header is *greater than* the LSN of the relevant write operation, then subsequent operations are also reflected in the query response. Follow the steps below to compare the LSNs for a write and a subsequent query. ### 1. Get the LSN for a write operation Every time you modify records in your namespace, the HTTP response contains the LSN for the upsert. This is contained in a header called `x-pinecone-request-lsn`. The following example demonstrates how to get the LSN for an `upsert` request using the `curl` option `-i`. This option tells curl to include headers in the displayed response. Use the same method to get the LSN for an `update` or `delete` request. ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -i "https://$INDEX_HOST/vectors/upsert" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "content-type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "vectors": [ { "id": "vec1", "values": [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8], } ], "namespace": "example-namespace" }' ``` The preceding request receives a response like the following example: ```shell curl theme={null} HTTP/2 200 date: Wed, 21 Aug 2024 15:23:04 GMT content-type: application/json content-length: 66 x-pinecone-request-lsn: 4 x-pinecone-request-latency-ms: 1149 x-pinecone-request-id: 3687967458925971419 x-envoy-upstream-service-time: 1150 grpc-status: 0 server: envoy {"upsertedCount":1} ``` In the preceding example response, the value of `x-pinecone-request-lsn` is 4. This is the LSN assigned to this write operation; use it to compare against the query response LSN in the next step. ### 2. Get the LSN for a query Every time you query your index, the HTTP response contains the LSN for the query. This is contained in a header called `x-pinecone-max-indexed-lsn`. By checking the LSN in your query results, you can confirm that the LSN is greater than or equal to the LSN of the relevant write operation, indicating that the results of that operation are present in the query results. The following example makes a `query` request to the index: ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -i "https://$INDEX_HOST/query" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "vector": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3], "namespace": "example-namespace", "topK": 3, "includeValues": true }' ``` The preceding request receives a response like the following example: ```shell theme={null} HTTP/2 200 date: Wed, 21 Aug 2024 15:33:36 GMT content-type: application/json content-length: 66 x-pinecone-max-indexed-lsn: 5 x-pinecone-request-latency-ms: 40 x-pinecone-request-id: 6683088825552978933 x-envoy-upstream-service-time: 41 grpc-status: 0 server: envoy { "results":[], "matches":[ { "id":"vec1", "score":0.891132772, "values":[0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8], } ], "namespace":"example-namespace", "usage":{"readUnits":6} } ``` In the preceding example response, the value of `x-pinecone-max-indexed-lsn` is 5. ### 3. Compare LSNs for writes and queries If the LSN of a query is greater than or equal to the LSN for a write operation, then the results of the query reflect the results of the write operation. In [step 1](#1-get-the-lsn-for-a-write-operation), the LSN contained in the response headers is 4. In [step 2](#2-get-the-lsn-for-a-query), the LSN contained in the response headers is 5. 5 is greater than or equal to 4; therefore, the results of the query reflect the results of the upsert. However, this does not guarantee that the records upserted are still present or unmodified: the write operation with LSN of 5 may have updated or deleted these records, or upserted additional records. ## Verify record counts If you insert new records or delete records, the number of records in the index may change. This means that the record count for an index can indicate whether Pinecone has indexed your latest inserts and deletes: if the record count for the index matches the count you expect after inserting or deleting records, the index is probably up-to-date. However, this is not always true. For example, if you delete the same number of records that you insert, the expected record count may remain the same. Also, some write operations, such as updates to an index configuration or vector data values, do not change the number of records in the index. To verify that your index contains the number of records you expect, [view index stats](/reference/api/latest/data-plane/describeindexstats): ```python Python theme={null} # pip install "pinecone[grpc]" from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.describe_index_stats() ``` ```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/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const stats = await index.describeIndexStats(); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.proto.DescribeIndexStatsResponse; public class DescribeIndexStatsExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); DescribeIndexStatsResponse indexStatsResponse = index.describeIndexStats(); System.out.println(indexStatsResponse); } } ``` ```go Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } stats, err := idxConnection.DescribeIndexStats(ctx) if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err) } else { fmt.Printf("%+v", *stats) } } ``` ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X POST "https://$INDEX_HOST/describe_index_stats" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` The response will look like this: ```Python Python theme={null} {'dimension': 1024, 'index_fullness': 0, 'namespaces': {'example-namespace1': {'vector_count': 4}, 'example-namespace2': {'vector_count': 4}}, 'total_vector_count': 8} ``` ```JavaScript JavaScript theme={null} Returns: { namespaces: { example-namespace1: { recordCount: 4 }, example-namespace2: { recordCount: 4 } }, dimension: 1024, indexFullness: 0, totalRecordCount: 8 } // Note: the value of totalRecordCount is the same as total_vector_count. ``` ```java Java theme={null} namespaces { key: "example-namespace1" value { vector_count: 4 } } namespaces { key: "example-namespace2" value { vector_count: 4 } } dimension: 1024 total_vector_count: 8 ``` ```go Go theme={null} { "dimension": 1024, "index_fullness": 0, "total_vector_count": 8, "namespaces": { "example-namespace1": { "vector_count": 4 }, "example-namespace2": { "vector_count": 4 } } } ``` ```shell curl theme={null} { "namespaces": { "example-namespace1": { "vectorCount": 4 }, "example-namespace2": { "vectorCount": 4 } }, "dimension": 1024, "indexFullness": 0, "totalVectorCount": 8 } ``` # Create an index Source: https://docs.pinecone.io/guides/index-data/create-an-index Create a Pinecone serverless index for full-text (BM25), semantic (dense vector), lexical (sparse), or hybrid search with a document schema. A Pinecone index can hold any combination of the following: * **Documents** are the unit of data in an index with a document schema — JSON records whose ranking fields are indexed according to a schema you declare at index creation. An index with a document schema can mix `dense_vector`, `sparse_vector`, and FTS-enabled `string` ranking fields in the same record, alongside any number of metadata fields (auto-indexed at upsert time). Use documents for [full-text search](/guides/search/full-text-search) (BM25 ranking on `string` fields with `full_text_search` enabled), and to combine multiple scoring methods on the same data via `score_by`. * **Dense vectors** are numerical representations of the meaning and relationships of text, images, or other data. Indexes of dense vectors are used for [semantic search](/guides/search/semantic-search), or together with sparse vectors for [hybrid search](/guides/search/hybrid-search). * **Sparse vectors** are high-dimensional vectors with mostly zero values, produced by a sparse embedding model such as [`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0). Indexes of sparse vectors are used for [sparse-vector lexical search](/guides/search/lexical-search), or together with dense vectors for [hybrid search](/guides/search/hybrid-search). You can create an index using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless). ## Create an index for full-text search An index with a document schema stores typed JSON documents. The schema declares how each ranking field is indexed: as a `string` field with `full_text_search` enabled for BM25 ranking, a `dense_vector` for ANN similarity, or a `sparse_vector`. A single index can mix all three ranking field types; at query time, pick the ranking signal with `score_by`. Metadata fields (anything else you upsert) are not declared in the schema — they're auto-indexed for filtering at upsert time. Full-text search is not integrated embedding. A `string` field with `full_text_search` is indexed for BM25 ranking and Lucene queries. It does not call an embedding model. Integrated embedding remains available for vector API indexes. Indexes with document schemas are in [public preview](/guides/search/full-text-search#public-preview) and use API version `2026-01.alpha`. The preview supports REST and the Python SDK; for other languages, call the REST endpoint directly. ### Minimal: BM25 on a single text field The example below creates an `articles` index whose `body` field is indexed for BM25 ranking. Other fields included at upsert time are stored on each document and auto-indexed for filtering as metadata. ```bash curl theme={null} curl -X POST "https://api.pinecone.io/indexes" \ -H "Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-01.alpha" \ -d '{ "name": "articles", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "body": { "type": "string", "full_text_search": {} } } } }' ``` ### Multi-field schema: BM25 + dense vector A single index with a document schema can hold FTS-enabled `string` and `dense_vector` ranking fields together (the same schema can also include a `sparse_vector` field). A single search request ranks by one scoring type — multi-field BM25 is supported (multiple `text` clauses on different fields, or one `query_string` clause spanning fields), and any scoring method can be combined with metadata filters, including text-match filters (`$match_phrase`, `$match_all`, `$match_any`) on FTS-enabled `string` fields. ```bash curl theme={null} curl -X POST "https://api.pinecone.io/indexes" \ -H "Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-01.alpha" \ -d '{ "name": "articles-multi", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "title": { "type": "string", "full_text_search": {} }, "body": { "type": "string", "full_text_search": {} }, "embedding":{ "type": "dense_vector", "dimension": 1536, "metric": "cosine" } } } }' ``` You can include additional fields (for example, `category` or `year`) at upsert time. All metadata fields are automatically indexed for filtering — they don't need to be declared in the schema. The schema is for ranking fields only; declaring a metadata-only field (`string` without `full_text_search`, `string_list`, `float`, or `boolean`) is rejected at index creation. For the full schema reference (all field types, language and analyzer options, dedicated read capacity, and Python SDK examples), see [Full-text search](/guides/search/full-text-search). Schema migration is not yet supported. Once an index with a document schema is created, you cannot add, remove, or modify fields. Plan your schema carefully — if you need to change a schema, [delete the index](/guides/manage-data/manage-indexes#delete-an-index) and create a new one. ## Create an index for dense vectors You can create an index that stores dense vectors with [integrated vector embedding](/guides/index-data/indexing-overview#integrated-embedding), or one that stores vectors generated with an external embedding model. ### Integrated embedding Indexes with integrated embedding do not support [updating](/guides/manage-data/update-data) or [importing](/guides/index-data/import-data) with text. If you want to upsert and search with source text and have Pinecone convert it to dense vectors automatically, [create an index with integrated embedding](/reference/api/latest/control-plane/create_for_model) as follows: * Provide a `name` for the index. * Set `cloud` and `region` to the [cloud and region](/guides/index-data/create-an-index#cloud-regions) where the index should be deployed. * Set `embed.model` to one of [Pinecone's hosted embedding models](/guides/index-data/create-an-index#embedding-models). * Set `embed.field_map` to the name of the field in your source document that contains the data for embedding. Other parameters are optional. See the [API reference](/reference/api/latest/control-plane/create_for_model) for details. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index_name = "integrated-dense-py" if not pc.has_index(index_name): pc.create_index_for_model( name=index_name, cloud="aws", region="us-east-1", embed={ "model":"llama-text-embed-v2", "field_map":{"text": "chunk_text"} } ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createIndexForModel({ name: 'integrated-dense-js', cloud: 'aws', region: 'us-east-1', embed: { model: 'llama-text-embed-v2', fieldMap: { text: 'chunk_text' }, }, waitUntilReady: true, }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.ApiException; import org.openapitools.db_control.client.model.CreateIndexForModelRequest; import org.openapitools.db_control.client.model.CreateIndexForModelRequestEmbed; import org.openapitools.db_control.client.model.DeletionProtection; import java.util.HashMap; import java.util.Map; public class CreateIntegratedIndex { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); String indexName = "integrated-dense-java"; String region = "us-east-1"; HashMap fieldMap = new HashMap<>(); fieldMap.put("text", "chunk_text"); CreateIndexForModelRequestEmbed embed = new CreateIndexForModelRequestEmbed() .model("llama-text-embed-v2") .fieldMap(fieldMap); Map tags = new HashMap<>(); tags.put("environment", "development"); pc.createIndexForModel( indexName, CreateIndexForModelRequest.CloudEnum.AWS, region, embed, DeletionProtection.DISABLED, tags ); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } indexName := "integrated-dense-go" deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreateIndexForModel(ctx, &pinecone.CreateIndexForModelRequest{ Name: indexName, Cloud: pinecone.Aws, Region: "us-east-1", Embed: pinecone.CreateIndexForModelEmbed{ Model: "llama-text-embed-v2", FieldMap: map[string]interface{}{"text": "chunk_text"}, }, DeletionProtection: &deletionProtection, Tags: &pinecone.IndexTags{ "environment": "development" }, }) if err != nil { log.Fatalf("Failed to create serverless integrated index: %v", idx.Name) } else { fmt.Printf("Successfully created serverless integrated index: %v", idx.Name) } } ``` ```json curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -X POST "https://api.pinecone.io/indexes/create-for-model" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "integrated-dense-curl", "cloud": "aws", "region": "us-east-1", "embed": { "model": "llama-text-embed-v2", "field_map": { "text": "chunk_text" } } }' ``` ```bash CLI theme={null} # Target the project where you want to create the index. pc target -o "example-org" -p "example-project" # Create the index. pc index create \ --name "integrated-dense-cli" \ --metric "cosine" \ --cloud "aws" \ --region "us-east-1" \ --model "llama-text-embed-v2" \ --field_map "text=chunk_text" \ --tags "environment=development" ``` ### Bring your own vectors If you use an external embedding model to convert your data to dense vectors, [create an index](/reference/api/latest/control-plane/create_index) as follows: * Provide a `name` for the index. * Set the `vector_type` to `dense`. * Specify the `dimension` and similarity `metric` of the vectors you'll store in the index. This should match the dimension and metric supported by your embedding model. * Set `spec.cloud` and `spec.region` to the [cloud and region](/guides/index-data/create-an-index#cloud-regions) where the index should be deployed. For Python, you also need to import the `ServerlessSpec` class. Other parameters are optional. See the [API reference](/reference/api/latest/control-plane/create_index) for details. ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key="YOUR_API_KEY") index_name = "standard-dense-py" if not pc.has_index(index_name): pc.create_index( name=index_name, vector_type="dense", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ), deletion_protection="disabled", tags={ "environment": "development" } ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createIndex({ name: 'standard-dense-js', vectorType: 'dense', dimension: 1536, metric: 'cosine', spec: { serverless: { cloud: 'aws', region: 'us-east-1' } }, deletionProtection: 'disabled', tags: { environment: 'development' }, }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.IndexModel; import org.openapitools.db_control.client.model.DeletionProtection; import java.util.HashMap; public class CreateServerlessIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); String indexName = "standard-dense-java"; String cloud = "aws"; String region = "us-east-1"; String vectorType = "dense"; Map tags = new HashMap<>(); tags.put("environment", "development"); pc.createServerlessIndex( indexName, "cosine", 1536, cloud, region, DeletionProtection.DISABLED, tags, vectorType ); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } // Serverless index indexName := "standard-dense-go" vectorType := "dense" dimension := int32(1536) metric := pinecone.Cosine deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: indexName, VectorType: &vectorType, Dimension: &dimension, Metric: &metric, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: &deletionProtection, Tags: &pinecone.IndexTags{ "environment": "development" }, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", err) } else { fmt.Printf("Successfully created serverless index: %v", idx.Name) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -X POST "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "standard-dense-curl", "vector_type": "dense", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "tags": { "environment": "development" }, "deletion_protection": "disabled" }' ``` ```bash CLI theme={null} # Target the project where you want to create the index. pc target -o "example-org" -p "example-project" # Create the index. pc index create \ --name "standard-dense-cli" \ --vector_type "dense" \ --dimension 1536 \ --metric "cosine" \ --cloud "aws" \ --region "us-east-1" \ --tags "environment=development" \ --deletion_protection "disabled" ``` ## Create an index for sparse vectors You can create an index that stores sparse vectors with [integrated vector embedding](/guides/index-data/indexing-overview#integrated-embedding), or one that stores vectors generated with an external embedding model. ### Integrated embedding If you want to upsert and search with source text and have Pinecone convert it to sparse vectors automatically, [create an index with integrated embedding](/reference/api/latest/control-plane/create_for_model) as follows: * Provide a `name` for the index. * Set `cloud` and `region` to the [cloud and region](/guides/index-data/create-an-index#cloud-regions) where the index should be deployed. * Set `embed.model` to one of [Pinecone's hosted sparse embedding models](/guides/index-data/create-an-index#embedding-models). * Set `embed.field_map` to the name of the field in your source document that contains the text for embedding. * If needed, `embed.read_parameters` and `embed.write_parameters` can be used to override the default model embedding behavior. Other parameters are optional. See the [API reference](/reference/api/latest/control-plane/create_for_model) for details. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index_name = "integrated-sparse-py" if not pc.has_index(index_name): pc.create_index_for_model( name=index_name, cloud="aws", region="us-east-1", embed={ "model":"pinecone-sparse-english-v0", "field_map":{"text": "chunk_text"} } ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createIndexForModel({ name: 'integrated-sparse-js', cloud: 'aws', region: 'us-east-1', embed: { model: 'pinecone-sparse-english-v0', fieldMap: { text: 'chunk_text' }, }, waitUntilReady: true, }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.ApiException; import org.openapitools.db_control.client.model.CreateIndexForModelRequest; import org.openapitools.db_control.client.model.CreateIndexForModelRequestEmbed; import org.openapitools.db_control.client.model.DeletionProtection; import java.util.HashMap; import java.util.Map; public class CreateIntegratedIndex { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); String indexName = "integrated-sparse-java"; String region = "us-east-1"; HashMap fieldMap = new HashMap<>(); fieldMap.put("text", "chunk_text"); CreateIndexForModelRequestEmbed embed = new CreateIndexForModelRequestEmbed() .model("pinecone-sparse-english-v0") .fieldMap(fieldMap); Map tags = new HashMap<>(); tags.put("environment", "development"); pc.createIndexForModel( indexName, CreateIndexForModelRequest.CloudEnum.AWS, region, embed, DeletionProtection.DISABLED, tags ); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } indexName := "integrated-sparse-go" deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreateIndexForModel(ctx, &pinecone.CreateIndexForModelRequest{ Name: indexName, Cloud: pinecone.Aws, Region: "us-east-1", Embed: pinecone.CreateIndexForModelEmbed{ Model: "pinecone-sparse-english-v0", FieldMap: map[string]interface{}{"text": "chunk_text"}, }, DeletionProtection: &deletionProtection, Tags: &pinecone.IndexTags{ "environment": "development" }, }) if err != nil { log.Fatalf("Failed to create serverless integrated index: %v", idx.Name) } else { fmt.Printf("Successfully created serverless integrated index: %v", idx.Name) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -X POST "https://api.pinecone.io/indexes/create-for-model" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "integrated-sparse-curl", "cloud": "aws", "region": "us-east-1", "embed": { "model": "pinecone-sparse-english-v0", "field_map": { "text": "chunk_text" } } }' ``` ```bash CLI theme={null} # Target the project where you want to create the index. pc target -o "example-org" -p "example-project" # Create the index. pc index create \ --name "integrated-sparse-cli" \ --cloud "aws" \ --region "us-east-1" \ --model "pinecone-sparse-english-v0" \ --field_map "text=chunk_text" \ --tags "environment=development" ``` ### Bring your own vectors If you use an external embedding model to convert your data to sparse vectors, [create an index](/reference/api/latest/control-plane/create_index) as follows: * Provide a `name` for the index. * Set the `vector_type` to `sparse`. * Set the distance `metric` to `dotproduct`. Indexes that store sparse vectors do not support other [distance metrics](/guides/index-data/indexing-overview#distance-metrics). * Set `spec.cloud` and `spec.region` to the cloud and region where the index should be deployed. Other parameters are optional. See the [API reference](/reference/api/latest/control-plane/create_index) for details. ```python Python theme={null} from pinecone import Pinecone, ServerlessSpec pc = Pinecone(api_key="YOUR_API_KEY") index_name = "standard-sparse-py" if not pc.has_index(index_name): pc.create_index( name=index_name, vector_type="sparse", metric="dotproduct", spec=ServerlessSpec(cloud="aws", region="us-east-1") ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createIndex({ name: 'standard-sparse-js', vectorType: 'sparse', metric: 'dotproduct', spec: { serverless: { cloud: 'aws', region: 'us-east-1' }, }, }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.DeletionProtection; import java.util.*; public class SparseIndex { public static void main(String[] args) throws InterruptedException { // Instantiate Pinecone class Pinecone pinecone = new Pinecone.Builder("YOUR_API_KEY").build(); // Create the index String indexName = "standard-sparse-java"; String cloud = "aws"; String region = "us-east-1"; String vectorType = "sparse"; Map tags = new HashMap<>(); tags.put("env", "test"); pinecone.createSparseServelessIndex(indexName, cloud, region, DeletionProtection.DISABLED, tags, vectorType); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } indexName := "standard-sparse-go" vectorType := "sparse" metric := pinecone.Dotproduct deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: indexName, Metric: &metric, VectorType: &vectorType, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: &deletionProtection, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", err) } else { fmt.Printf("Successfully created serverless index: %v", idx.Name) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -X POST "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "standard-sparse-curl", "vector_type": "sparse", "metric": "dotproduct", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } } }' ``` ```bash CLI theme={null} # Target the project where you want to create the index. pc target -o "example-org" -p "example-project" # Create the index. pc index create \ --name "standard-sparse-cli" \ --vector_type "sparse" \ --metric "dotproduct" \ --cloud "aws" \ --region "us-east-1" \ --tags "environment=development" ``` ## Create an index from a backup You can restore an index from a backup, regardless of whether it stores dense or sparse vectors. For more details, see [Restore an index](/guides/manage-data/restore-an-index). ## Metadata indexing This feature is in [early access](/release-notes/feature-availability) and available only on the `2025-10` version of the API. The CLI does not yet support this feature. Pinecone indexes all metadata fields by default. However, large amounts of metadata can cause slower [index building](/guides/get-started/database-architecture#index-builder) as well as slower [query execution](/guides/get-started/database-architecture#query-executors), particularly when data is not cached in a query executor's memory and local SSD and must be fetched from object storage. To prevent performance issues due to excessive metadata, you can limit metadata indexing to the fields that you plan to use for [query filtering](/guides/search/filter-by-metadata). ### Set metadata indexing You can set metadata indexing during index creation or [namespace creation](/reference/api/2025-10/data-plane/createnamespace): * Index-level metadata indexing rules apply to all namespaces that don't have explicit metadata indexing rules. * Namespace-level metadata indexing rules overrides index-level metadata indexing rules. For example, let's say you want to store records that represent chunks of a document, with each record containing many metadata fields. Since you plan to use only a few of the metadata fields to filter queries, you would specify the metadata fields to index as follows. Metadata indexing cannot be changed after index or namespace creation. ```shell Index-level metadata indexing theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "example-index-metadata", "vector_type": "dense", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1", "schema": { "fields": { "document_id": { "filterable": true }, "document_title": { "filterable": true }, "chunk_number": { "filterable": true }, "document_url": { "filterable": true }, "created_at": { "filterable": true } } } } }, "deletion_protection": "disabled" }' ``` ```shell Namespace-level metadata indexing theme={null} # To learn how to get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/namespaces" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "example-namespace", "schema": { "fields": { "document_id": { "filterable": true }, "document_title": { "filterable": true }, "chunk_number": { "filterable": true }, "document_url": { "filterable": true }, "created_at": { "filterable": true } } } }' ``` ### Check metadata indexing To check which metadata fields are indexed, you can describe the index or namespace: ```shell Describe index theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -X GET "https://api.pinecone.io/indexes/example-index-metadata" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ```shell Describe namespace theme={null} # To learn how to get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/namespaces/example-namespace" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` The response includes the `schema` object with the names of the metadata fields explicitly indexed during index or namespace creation. The response does not include unindexed metadata fields or metadata fields indexed by default. ```json Describe index theme={null} { "id": "751ab850-6e61-4f92-bd23-fa129803d207", "vector_type": "dense", "name": "example-index", "metric": "cosine", "dimension": 1536, "status": { "ready": false, "state": "Initializing" }, "host": "example-index-fa77d8e.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "OnDemand", "status": "Ready" }, "schema": { "fields": { "document_id": { "filterable": true }, "document_title": { "filterable": true }, "created_at": { "filterable": true }, "chunk_number": { "filterable": true }, "document_url": { "filterable": true } } } } }, "deletion_protection": "disabled", "tags": null } ``` ```json Describe namespace theme={null} { "name": "example-namespace", "record_count": "20000", "schema": { "fields": { "document_title": { "filterable": true }, "document_url": { "filterable": true }, "chunk_number": { "filterable": true }, "document_id": { "filterable": true }, "created_at": { "filterable": true } } } } ``` ## Index options ### Cloud regions When creating an index, you must choose the cloud and region where you want the index to be hosted. The following table lists the available public clouds and regions and the plans that support them: | Cloud | Region | [Supported plans](https://www.pinecone.io/pricing/) | [Availability phase](/release-notes/feature-availability) | | ------- | ---------------------------- | --------------------------------------------------- | --------------------------------------------------------- | | `aws` | `us-east-1` (Virginia) | Starter, Builder, Standard, Enterprise | General availability | | `aws` | `us-west-2` (Oregon) | Builder, Standard, Enterprise | General availability | | `aws` | `eu-west-1` (Ireland) | Builder, Standard, Enterprise | General availability | | `aws` | `eu-central-1` (Frankfurt) | Builder, Standard, Enterprise | General availability | | `aws` | `ap-southeast-1` (Singapore) | Builder, Standard, Enterprise | General availability | | `gcp` | `us-central1` (Iowa) | Builder, Standard, Enterprise | General availability | | `gcp` | `europe-west4` (Netherlands) | Builder, Standard, Enterprise | General availability | | `azure` | `eastus2` (Virginia) | Builder, Standard, Enterprise | General availability | The cloud and region cannot be changed after a serverless index is created. On the Starter plan, you can create serverless indexes in the `us-east-1` region of AWS only. To create indexes in other regions, [upgrade to the Builder, Standard, or Enterprise plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Similarity metrics When creating an index that stores dense vectors, you can choose from the following similarity metrics. For the most accurate results, choose the similarity metric used to train the embedding model for your vectors. For more information, see [Vector Similarity Explained](https://www.pinecone.io/learn/vector-similarity/). Indexes that store [sparse vectors](#sparse-indexes) must use the `dotproduct` metric. Querying indexes with this metric returns a similarity score equal to the squared Euclidean distance between the result and query vectors. This metric calculates the square of the distance between two data points in a plane. It is one of the most commonly used distance metrics. For an example, see our [IT threat detection example](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/it-threat-detection.ipynb). When you use `metric='euclidean'`, the most similar results are those with the **lowest similarity score**. This is often used to find similarities between different documents. The advantage is that the scores are normalized to \[-1,1] range. For an example, see our [generative question answering example](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/gen-qa-openai.ipynb). This is used to multiply two vectors. You can use it to tell us how similar the two vectors are. The more positive the answer is, the closer the two vectors are in terms of their directions. For an example, see our [semantic search example](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/semantic-search.ipynb). ### Embedding models [Dense vectors](/guides/get-started/concepts#dense-vector) and [sparse vectors](/guides/get-started/concepts#sparse-vector) are the basic units of data in Pinecone and what Pinecone was specially designed to store and work with. Dense vectors represents the semantics of data such as text, images, and audio recordings, while sparse vectors represent documents or queries in a way that captures keyword information. To transform data into vector format, you use an embedding model. Pinecone hosts several embedding models so it's easy to manage your vector storage and search process on a single platform. You can use a hosted model to embed your data as an integrated part of upserting and querying, or you can use a hosted model to embed your data as a standalone operation. The following embedding models are hosted by Pinecone. To understand how cost is calculated for embedding, see [Embedding cost](/guides/manage-cost/understanding-cost#embedding). To get model details via the API, see [List models](/reference/api/latest/inference/list_models) and [Describe a model](/reference/api/latest/inference/describe_model). #### multilingual-e5-large [`multilingual-e5-large`](/models/multilingual-e5-large) is an efficient dense embedding model trained on a mixture of multilingual datasets. It works well on messy data and short queries expected to return medium-length passages of text (1-2 paragraphs). **Details** * Vector type: Dense * Modality: Text * Dimension: 1024 * Recommended similarity metric: Cosine * Max sequence length: 507 tokens * Max batch size: 96 sequences For rate limits, see [Embedding tokens per minute](/reference/api/database-limits#embedding-tokens-per-minute-per-model) and [Embedding tokens per month](/reference/api/database-limits#embedding-tokens-per-month-per-model). **Parameters** The `multilingual-e5-large` model supports the following parameters: | Parameter | Type | Required/Optional | Description | Default | | :----------- | :----- | :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ | | `input_type` | string | Required | The type of input data. Accepted values: `query` or `passage`. | | | `truncate` | string | Optional | How to handle inputs longer than those supported by the model. Accepted values: `END` or `NONE`.

`END` truncates the input sequence at the input token limit. `NONE` returns an error when the input exceeds the input token limit. | `END` | #### llama-text-embed-v2 [`llama-text-embed-v2`](/models/llama-text-embed-v2) is a high-performance dense embedding model optimized for text retrieval and ranking tasks. It is trained on a diverse range of text corpora and provides strong performance on longer passages and structured documents. **Details** * Vector type: Dense * Modality: Text * Dimension: 1024 (default), 2048, 768, 512, 384 * Recommended similarity metric: Cosine * Max sequence length: 2048 tokens * Max batch size: 96 sequences For rate limits, see [Embedding tokens per minute](/reference/api/database-limits#embedding-tokens-per-minute-per-model) and [Embedding tokens per month](/reference/api/database-limits#embedding-tokens-per-month-per-model). **Parameters** The `llama-text-embed-v2` model supports the following parameters: | Parameter | Type | Required/Optional | Description | Default | | :----------- | :------ | :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ | | `input_type` | string | Required | The type of input data. Accepted values: `query` or `passage`. | | | `truncate` | string | Optional | How to handle inputs longer than those supported by the model. Accepted values: `END` or `NONE`.

`END` truncates the input sequence at the input token limit. `NONE` returns an error when the input exceeds the input token limit. | `END` | | `dimension` | integer | Optional | Dimension of the vector to return. | 1024 | #### pinecone-sparse-english-v0 [`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0) is a sparse embedding model for converting text to [sparse vectors](/guides/get-started/concepts#sparse-vector) for [sparse-vector lexical search](/guides/search/lexical-search) or hybrid search. Built on the innovations of the [DeepImpact architecture](https://arxiv.org/pdf/2104.12016), the model directly estimates the lexical importance of tokens by leveraging their context, unlike traditional retrieval models like BM25, which rely solely on term frequency. **Details** * Vector type: Sparse * Modality: Text * Recommended similarity metric: Dotproduct * Max sequence length: 512 or 2048 * Max batch size: 96 sequences For rate limits, see [Embedding tokens per minute](/reference/api/database-limits#embedding-tokens-per-minute-per-model) and [Embedding tokens per month](/reference/api/database-limits#embedding-tokens-per-month-per-model). **Parameters** The `pinecone-sparse-english-v0` model supports the following parameters: | Parameter | Type | Required/Optional | Description | Default | | :------------------------ | :------ | :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ | | `input_type` | string | Required | The type of input data. Accepted values: `query` or `passage`. | | | `max_tokens_per_sequence` | integer | Optional | Maximum number of tokens to embed. Accepted values: `512` or `2048`. | `512` | | `truncate` | string | Optional | How to handle inputs longer than those supported by the model. Accepted values: `END` or `NONE`.

`END` truncates the input sequence at the the `max_tokens_per_sequence` limit. `NONE` returns an error when the input exceeds the `max_tokens_per_sequence` limit. | `END` | | `return_tokens` | boolean | Optional | Whether to return the string tokens. | `false` | # Data ingestion overview Source: https://docs.pinecone.io/guides/index-data/data-ingestion-overview Compare data ingestion options in Pinecone: bulk import from object storage, upsert operations, and hosted embedding via the Inference API. To control costs when ingesting large datasets (10,000,000+ records), use [import](/guides/index-data/import-data) instead of upsert. ## Import from object storage [Importing from object storage](/guides/index-data/import-data) is the most efficient and cost-effective method to load large numbers of records into an index. You store your data as Parquet files in object storage, integrate your object storage with Pinecone, and then start an asynchronous, long-running operation that imports and indexes your records. This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). ## Upsert For ongoing ingestion into an index, either one record at a time or in batches, use the [upsert](/guides/index-data/upsert-data) operation. [Batch upserting](/guides/index-data/upsert-data#upsert-in-batches) can improve throughput performance and is a good option for larger numbers of records if you cannot work around import's current [limitations](/guides/index-data/import-data#import-limits). ## When you only need embeddings Import and upsert move vectors into Pinecone. For workflows where you only need vectors from hosted models (for example, to embed offline and upsert later), use the Inference API as follows: You can call the [`embed` operation](/reference/api/latest/inference/generate-embeddings) through Pinecone Inference to turn text into vectors without writing to an index. That differs from [`upsert_records`](/reference/api/latest/data-plane/upsert_records) on an index with integrated embedding, where each request embeds and stores records in one step. To see how embedding consumption appears in billing and usage reports, see [Embedding tokens](/guides/manage-cost/monitor-usage-and-costs#embedding-tokens). ## Ingestion cost * To understand how cost is calculated for imports, see [Import cost](/guides/manage-cost/understanding-cost#imports). * To understand how cost is calculated for upserts, see [Write unit pricing](/guides/manage-cost/understanding-cost#write-units). * For up-to-date pricing information, see [Pricing](https://www.pinecone.io/pricing/). ## Data freshness Pinecone is eventually consistent, so there can be a slight delay before new or changed records are visible to queries. You can view index stats to [check data freshness](/guides/index-data/check-data-freshness). # Data modeling Source: https://docs.pinecone.io/guides/index-data/data-modeling Model your data in Pinecone using documents with dense_vector, sparse_vector, full-text string, and metadata fields for efficient retrieval. Pinecone has two ways to model your data, and the choice is made when you create the index: an index created with a document schema holds documents, while an index created with a dense or sparse vector type holds records. Both hold a unique `_id` and optional metadata and live in [namespaces](/guides/index-data/indexing-overview#namespaces); they differ in how many ranking signals a single item can carry and which API you call. Both are fully supported. * **[Documents](#documents)** are the unit of data in an index with a **document schema**, the model behind [full-text search](/guides/search/full-text-search). A document is a JSON object that can carry text fields (ranked with BM25 and Lucene queries), a dense vector, a sparse vector, and metadata in a single index, and you pick the ranking signal per query with `score_by`. Use documents for text-first search or any workload that needs more than one ranking signal in one index. * **[Records](#records)** are the unit of data for [indexes with dense vectors](/guides/get-started/concepts#index-with-dense-vectors) and [indexes with sparse vectors](/guides/get-started/concepts#index-with-sparse-vectors), the vector API. A record carries one vector (or raw text for Pinecone to embed) plus metadata. Use records for vector-only workloads. ## Documents A document is the unit of data in an index with a document schema — a JSON object with a required `_id` field, the ranking fields declared in the index's schema, and any number of metadata fields. Documents support multiple field types in a single record: a `dense_vector` field (for [semantic search](/guides/search/semantic-search)), a `sparse_vector` field (for [sparse-vector lexical search](/guides/search/lexical-search)), one or more `string` fields with `full_text_search` enabled (for [full-text search](/guides/search/full-text-search) with BM25 and Lucene queries), plus any metadata you upsert alongside them. The schema, declared at index creation, tells Pinecone how to rank each ranking field. Schema field types: * `dense_vector` — indexed for ANN similarity search. * `sparse_vector` — indexed for sparse-vector lexical search. * `string` with a nested `full_text_search` config object (`{}` enables with all defaults; optional sub-fields: `language`, `stemming`, `stop_words`) — indexed for **BM25** ranking and Lucene queries. Lowercasing and the token length cap are server-applied and cannot be overridden. Metadata fields are not declared in the schema. Any field you upsert that is not declared in the schema is stored on the document, returned via `include_fields`, and automatically indexed for filtering. Pinecone infers the metadata field type from the values you upsert: strings, numbers (floating point), booleans, and arrays of strings are all supported. Document fields can hold structured values: a metadata `string_list` field holds an array of strings; a `dense_vector` field holds an array of floats; a `sparse_vector` field is an object with two parallel arrays — `indices` (token positions) and `values` (token weights). A schema can declare up to 100 `string` fields with `full_text_search` enabled, but at most one `dense_vector` field and at most one `sparse_vector` field per index. Example document for an index with `title`, `body`, `embedding`, and `category` fields: ```json theme={null} { "_id": "document1#chunk1", "title": "Introduction to Vector Databases", "body": "First chunk of the document content...", "embedding": [0.0236, -0.0329, ..., -0.0104, 0.0086], "category": "tutorial" } ``` Field-name rules: * Must be unique, non-empty strings. * Must not start with `_` (reserved for system-managed fields like `_id` and `_score`) or `$` (reserved for filter operators). * Limited to 64 bytes. For the full schema reference (language and analyzer options, multi-field schemas, scoring methods), see [Full-text search](/guides/search/full-text-search). **Chunking granularity.** A document is the unit of retrieval — `top_k` and `_score` are computed per document, not per sub-section. In public preview, Pinecone does not split a single document into multiple in-document chunks at index time. If your source content is longer than what you want to retrieve as one hit (a long article, a PDF, a transcript), do the chunking in your application before upsert and store each chunk as its own document, with an ID like `document1#chunk1`, `document1#chunk2`, and a metadata field that ties chunks back to the parent document for grouping at query time. ### Schema patterns The same document model supports several common schema shapes. Pick the one that matches the signal you want to rank by, and plan your fields up front: in public preview, schema migration is not supported after index creation. Filters are deterministic per document and apply before scoring; choose your hard yes/no constraints (including text-match operators on FTS-enabled `string` fields) first, then pick a `score_by` method to rank whatever remains. See [Filters vs. scoring](/guides/search/full-text-search#filters-vs-scoring). The Python snippets in each accordion below assume an initialized client and the schema-builder import: ```python Python theme={null} from pinecone import Pinecone from pinecone.preview import SchemaBuilder pc = Pinecone(api_key="YOUR_API_KEY") ``` Each accordion shows the pattern-specific schema, an example document, and a search snippet. The control-plane (`pc.preview.indexes.create(...)`) and data-plane (`index = pc.preview.index(name=...)`) calls in the snippets reuse this `pc`. Use when you want BM25 keyword ranking on one piece of text per document (a review body, a support ticket, a product description) and you don't have embeddings to manage. ```python Python theme={null} from pinecone.preview import SchemaBuilder schema = ( SchemaBuilder() .add_string_field("review_text", full_text_search={"language": "en"}) .build() ) pc.preview.indexes.create(name="book-reviews", schema=schema) ``` A document upserted into this index looks like: ```json theme={null} { "_id": "review-1234", "review_text": "Beautifully written exploration of contact, communication, and civilization across cosmic distances. The pacing is uneven but the central premise carries you through." } ``` Search with a single `text` clause (the score\_by `type`, not a field type — this clause runs BM25 ranking on the named string field): ```python Python theme={null} index.documents.search( namespace="reviews", top_k=10, score_by=[{"type": "text", "field": "review_text", "query": "civilization"}], ) ``` See [Full-text search](/guides/search/full-text-search). Use when a document has more than one piece of text that should both contribute to ranking — for example, a long `review_text` plus a short `review_summary`. Pinecone combines the per-field BM25 scores into one ranking per document. ```python Python theme={null} schema = ( SchemaBuilder() .add_string_field("review_text", full_text_search={"language": "en"}) .add_string_field("review_summary", full_text_search={"language": "en"}) .build() ) pc.preview.indexes.create(name="book-reviews-multi", schema=schema) ``` A document upserted into this index looks like: ```json theme={null} { "_id": "review-1234", "review_text": "Beautifully written exploration of contact, communication, and civilization across cosmic distances. The pacing is uneven but the central premise carries you through.", "review_summary": "Monumental science fiction with uneven pacing", "category": "science-fiction", "rating": 4.5 } ``` `category` and `rating` are not declared in the schema — they're upserted as metadata, automatically indexed for filtering, and usable in `filter` expressions. Pass two `text` clauses in `score_by`; the server combines them into one ranking, with each contributing field weighted equally in `2026-01.alpha`. ```python Python theme={null} index = pc.preview.index(name="book-reviews-multi") index.documents.search( namespace="reviews", top_k=5, score_by=[ {"type": "text", "field": "review_text", "query": "disappointing"}, {"type": "text", "field": "review_summary", "query": "Disappointing"}, ], include_fields=["*"], ) ``` Most workloads that combine semantic ranking with keyword matching reach for this pattern: rank by dense (or sparse) similarity, restricted to documents that contain a specific term or phrase. Common examples include semantic search over patents, regulatory filings, internal knowledge bases, or other technical literature where the right answer must contain a specific term. A single schema can include one `dense_vector` field plus any number of FTS-enabled string fields: ```python Python theme={null} schema = ( SchemaBuilder() .add_string_field("book_title", full_text_search={"language": "en"}) .add_string_field("review_text", full_text_search={"language": "en"}) .add_dense_vector_field("review_embedding", dimension=1024, metric="cosine") .build() ) pc.preview.indexes.create(name="book-reviews-dense", schema=schema) ``` A document upserted into this index looks like: ```json theme={null} { "_id": "review-1234", "book_title": "The Three-Body Problem", "review_text": "Beautifully written exploration of contact, communication, and civilization across cosmic distances.", "review_embedding": [0.012, -0.087, 0.153, ...] } ``` `review_embedding` is a 1024-dim list of floats produced by your dense embedding model. Use the same model at query time so the query vector lives in the same space. A single search request ranks by one scoring type. With this schema you have two query options: **Option A — dense ranking restricted by a text-match filter** (the most common hybrid pattern): ```python Python theme={null} index = pc.preview.index(name="book-reviews-dense") # query_embedding is a 1024-dim list of floats from your embedding model. query_embedding = embed("beautifully written, hard sci-fi") index.documents.search( namespace="reviews", top_k=5, score_by=[ {"type": "dense_vector", "field": "review_embedding", "values": query_embedding}, ], filter={"review_text": {"$match_phrase": "beautifully written"}}, ) ``` **Option B — run BM25 and dense searches separately and merge client-side** (when you want both signals to contribute to ranking, e.g. via [reciprocal rank fusion](/guides/search/reciprocal-rank-fusion)): ```python Python theme={null} dense_hits = index.documents.search( namespace="reviews", top_k=50, score_by=[{"type": "dense_vector", "field": "review_embedding", "values": query_embedding}], ) bm25_hits = index.documents.search( namespace="reviews", top_k=50, score_by=[{"type": "text", "field": "review_text", "query": "beautifully written"}], ) # Merge dense_hits + bm25_hits in your application (e.g. RRF) to produce final ranking. ``` See [Hybrid search](/guides/search/hybrid-search) for a fuller discussion. The `dense_vector` field's source content is independent of the FTS-enabled `string` fields it sits alongside. You can embed images (e.g., with a multimodal model like Gemini Embedding 2 or a CLIP-style model) and pair them with FTS-enabled `string` fields holding captions, geography, or taxonomy — then query the image vector with a text description and restrict matches with FTS filters on those `string` fields. The schema doesn't constrain what the dense vector represents; it just stores a vector of the declared dimension. Use when a single document is best described by more than one ranking signal — for example, a video catalog where each item has frame embeddings (dense), auto-generated captions you've encoded as sparse vectors (sparse), and a transcript text field (BM25/Lucene). One schema declares all three; you pick the ranking signal per query with `score_by`. No second index, no cross-index linkage to maintain. ```python Python theme={null} schema = ( SchemaBuilder() .add_dense_vector_field("frame_embedding", dimension=1024, metric="cosine") .add_sparse_vector_field("caption_sparse") .add_string_field("transcript", full_text_search={"language": "en"}) .build() ) pc.preview.indexes.create(name="video-catalog", schema=schema) ``` A `language` field upserted alongside these ranking fields is treated as metadata: stored on the document, returned via `include_fields`, and auto-indexed for filtering. A document upserted into this index looks like: ```json theme={null} { "_id": "video-7890#scene-3", "frame_embedding": [0.012, -0.087, 0.153, ...], "caption_sparse": { "indices": [42, 1077, 9821], "values": [0.41, 0.33, 0.18] }, "transcript": "I think we should go now before it gets dark.", "language": "en" } ``` `frame_embedding` is a 1024-dim list of floats from your dense vision model. `caption_sparse` is the output of your sparse encoder — an object with parallel `indices` (token IDs) and `values` (token weights) arrays. The same index supports three different query shapes. All three assume: ```python Python theme={null} index = pc.preview.index(name="video-catalog") # Replace with the outputs of your encoders. query_embedding = embed_image(query_image) # 1024-dim list of floats query_sparse = sparse_encode("scene with a lighthouse") # {"indices": [...], "values": [...]} ``` **Semantic frame search** — rank by visual similarity: ```python Python theme={null} index.documents.search( namespace="videos", top_k=10, score_by=[{"type": "dense_vector", "field": "frame_embedding", "values": query_embedding}], ) ``` **Caption lexical search** — rank by sparse-vector lexical similarity over your encoded captions: ```python Python theme={null} index.documents.search( namespace="videos", top_k=10, score_by=[{"type": "sparse_vector", "field": "caption_sparse", "sparse_values": query_sparse}], ) ``` **Semantic search restricted to spoken phrase** — semantic frame ranking, narrowed to clips where the transcript contains a specific phrase: ```python Python theme={null} index.documents.search( namespace="videos", top_k=10, score_by=[{"type": "dense_vector", "field": "frame_embedding", "values": query_embedding}], filter={"transcript": {"$match_phrase": "I love you"}}, ) ``` `score_by` selects one ranking signal per request, but every signal stays addressable on the same documents. Use when you're modeling data with the [vector API](#records) (not the document API) and want to combine a sparse and dense vector in one record on a single index. For new document-centric projects with text data, prefer the document-shape Dense + FTS pattern above. ```json theme={null} { "id": "doc1#chunk1", "values": [0.0236, -0.0329, ..., -0.0104, 0.0086], "sparse_values": { "indices": [822745112, 1009084850, ...], "values": [1.7958984, 0.41577148, ...] }, "metadata": { "document_id": "doc1", "chunk_number": 1 } } ``` See [Hybrid search](/guides/search/hybrid-search). ## Records Records are how you model data for [indexes with dense vectors](/guides/get-started/concepts#index-with-dense-vectors) and [indexes with sparse vectors](/guides/get-started/concepts#index-with-sparse-vectors). Each record carries one vector (dense, sparse, or both for single-index hybrid) plus optional metadata, and you can upsert raw text in place of a vector when the index is [integrated with an embedding model](/guides/index-data/create-an-index#embedding-models). When you upsert pre-generated vectors, each record consists of the following: * **ID**: A unique string identifier for the record. * **Vector**: A dense vector for [semantic search](/guides/search/semantic-search), a sparse vector for [sparse-vector lexical search](/guides/search/lexical-search), or both for single-index [hybrid search](/guides/search/hybrid-search) (vector API). * **Metadata** (optional): A flat JSON document containing key-value pairs with additional information (nested objects are not supported). You can filter by metadata when searching or deleting records. When importing data from object storage, records must be in Parquet format. For more details, see [Import data](/guides/index-data/import-data#prepare-your-data). Example: ```json Dense theme={null} { "id": "document1#chunk1", "values": [0.0236663818359375, -0.032989501953125, ..., -0.01041412353515625, 0.0086669921875], "metadata": { "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 1, "chunk_text": "First chunk of the document content...", "document_url": "https://example.com/docs/document1", "created_at": "2024-01-15", "document_type": "tutorial" } } ``` ```json Sparse theme={null} { "id": "document1#chunk1", "sparse_values": { "values": [1.7958984, 0.41577148, ..., 4.4414062, 3.3554688], "indices": [822745112, 1009084850, ..., 3517203014, 3590924191] }, "metadata": { "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 1, "chunk_text": "First chunk of the document content...", "document_url": "https://example.com/docs/document1", "created_at": "2024-01-15", "document_type": "tutorial" } } ``` ```json Hybrid theme={null} { "id": "document1#chunk1", "values": [0.0236663818359375, -0.032989501953125, ..., -0.01041412353515625, 0.0086669921875], "sparse_values": { "values": [1.7958984, 0.41577148, ..., 4.4414062, 3.3554688], "indices": [822745112, 1009084850, ..., 3517203014, 3590924191] }, "metadata": { "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 1, "chunk_text": "First chunk of the document content...", "document_url": "https://example.com/docs/document1", "created_at": "2024-01-15", "document_type": "tutorial" } } ``` When you upsert raw text for Pinecone to convert to vectors automatically, each record consists of the following: * **ID**: A unique string identifier for the record. * **Text**: The raw text for Pinecone to convert to a dense vector for [semantic search](/guides/search/semantic-search) or a sparse vector for [sparse-vector lexical search](/guides/search/lexical-search), depending on the [embedding model](/guides/index-data/create-an-index#embedding-models) integrated with the index. This field name must match the `embed.field_map` defined in the index. * **Metadata** (optional): All additional fields are stored as record metadata. You can filter by metadata when searching or deleting records. Upserting raw text is supported only for [indexes with integrated embedding](/guides/index-data/indexing-overview#vector-embedding). Example: ```json theme={null} { "_id": "document1#chunk1", "chunk_text": "First chunk of the document content...", // Text to convert to a vector. "document_id": "document1", // This and subsequent fields stored as metadata. "document_title": "Introduction to Vector Databases", "chunk_number": 1, "document_url": "https://example.com/docs/document1", "created_at": "2024-01-15", "document_type": "tutorial" } ``` ## Use structured IDs Use a structured, human-readable format for record IDs, including ID prefixes that reflect the type of data you're storing, for example: * **Document chunks**: `document_id#chunk_number` * **User data**: `user_id#data_type#item_id` * **Multi-tenant data**: `tenant_id#document_id#chunk_id` Choose a delimiter for your ID prefixes that won't appear elsewhere in your IDs. Common patterns include: * `document1#chunk1` - Using hash delimiter * `document1_chunk1` - Using underscore delimiter * `document1:chunk1` - Using colon delimiter Structuring IDs in this way provides several advantages: * **Efficiency**: Applications can quickly identify which record it should operate on. * **Clarity**: Developers can easily understand what they're looking at when examining records. * **Flexibility**: ID prefixes enable list operations for fetching and updating records. ## Include metadata Include [metadata key-value pairs](/guides/index-data/indexing-overview#metadata) that support your application's key operations, for example: * **Enable query-time filtering**: Add fields for time ranges, categories, or other criteria for [filtering searches for increased accuracy and relevance](/guides/search/filter-by-metadata). * **Link related chunks**: Use fields like `document_id` and `chunk_number` to keep track of related records and enable efficient [chunk deletion](#delete-chunks) and [document updates](#update-an-entire-document). * **Link back to original data**: Include `chunk_text` or `document_url` for traceability and user display. Metadata keys must be strings, and metadata values must be one of the following data types: * String * Number (stored as a 64-bit floating point) * Boolean (true, false) * List of strings Pinecone supports 40 KB of metadata per record. ## Example This example demonstrates how to manage document chunks in Pinecone using structured IDs and comprehensive metadata. It covers the complete lifecycle of chunked documents: upserting, searching, fetching, updating, and deleting chunks, and updating an entire document. ### Upsert chunks When [upserting](/guides/index-data/upsert-data) documents that have been split into chunks, combine structured IDs with comprehensive metadata: Upserting raw text is supported only for [indexes with integrated embedding](/guides/index-data/create-an-index#integrated-embedding). ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.upsert_records( "example-namespace", [ { "_id": "document1#chunk1", "chunk_text": "First chunk of the document content...", "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 1, "document_url": "https://example.com/docs/document1", "created_at": "2024-01-15", "document_type": "tutorial" }, { "_id": "document1#chunk2", "chunk_text": "Second chunk of the document content...", "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 2, "document_url": "https://example.com/docs/document1", "created_at": "2024-01-15", "document_type": "tutorial" }, { "_id": "document1#chunk3", "chunk_text": "Third chunk of the document content...", "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 3, "document_url": "https://example.com/docs/document1", "created_at": "2024-01-15", "document_type": "tutorial" }, ] ) ``` ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.upsert( namespace="example-namespace", vectors=[ { "id": "document1#chunk1", "values": [0.0236663818359375, -0.032989501953125, ..., -0.01041412353515625, 0.0086669921875], "metadata": { "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 1, "chunk_text": "First chunk of the document content...", "document_url": "https://example.com/docs/document1", "created_at": "2024-01-15", "document_type": "tutorial" } }, { "id": "document1#chunk2", "values": [-0.0412445068359375, 0.028839111328125, ..., 0.01953125, -0.0174560546875], "metadata": { "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 2, "chunk_text": "Second chunk of the document content...", "document_url": "https://example.com/docs/document1", "created_at": "2024-01-15", "document_type": "tutorial" } }, { "id": "document1#chunk3", "values": [0.0512237548828125, 0.041656494140625, ..., 0.02130126953125, -0.0394287109375], "metadata": { "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 3, "chunk_text": "Third chunk of the document content...", "document_url": "https://example.com/docs/document1", "created_at": "2024-01-15", "document_type": "tutorial" } } ] ) ``` ### Search chunks To search the chunks of a document, use a [metadata filter expression](/guides/search/filter-by-metadata#metadata-filter-expressions) that limits the search appropriately: Searching with text is supported only for [indexes with integrated embedding](/guides/index-data/create-an-index#integrated-embedding). ```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/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") filtered_results = index.search( namespace="example-namespace", query={ "inputs": {"text": "What is a vector database?"}, "top_k": 3, "filter": {"document_id": "document1"} }, fields=["chunk_text"] ) print(filtered_results) ``` ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") filtered_results = index.query( namespace="example-namespace", vector=[0.0236663818359375,-0.032989501953125, ..., -0.01041412353515625,0.0086669921875], top_k=3, filter={ "document_id": {"$eq": "document1"} }, include_metadata=True, include_values=False ) print(filtered_results) ``` ### Fetch chunks To retrieve all chunks for a specific document, first [list the record IDs](/guides/manage-data/list-record-ids) using the document prefix, and then [fetch](/guides/manage-data/fetch-data) the complete records: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") # List all chunks for document1 using ID prefix chunk_ids = [] for record_id in index.list(prefix='document1#', namespace='example-namespace'): chunk_ids.append(record_id) print(f"Found {len(chunk_ids)} chunks for document1") # Fetch the complete records by ID if chunk_ids: records = index.fetch(ids=chunk_ids, namespace='example-namespace') for record_id, record_data in records['vectors'].items(): print(f"Chunk ID: {record_id}") print(f"Chunk text: {record_data['metadata']['chunk_text']}") # Process the vector values and metadata as needed ``` Pinecone is [eventually consistent](/guides/index-data/check-data-freshness), so it's possible that a write (upsert, update, or delete) followed immediately by a read (query, list, or fetch) may not return the latest version of the data. If your use case requires retrieving data immediately, consider implementing a small delay or [retry logic](/guides/production/error-handling#implement-retry-logic) after writes. ### Update chunks To [update](/guides/manage-data/update-data) specific chunks within a document, first list the chunk IDs, and then update individual records: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") # List all chunks for document1 chunk_ids = [] for record_id in index.list(prefix='document1#', namespace='example-namespace'): chunk_ids.append(record_id) # Update specific chunks (e.g., update chunk 2) if 'document1#chunk2' in chunk_ids: new_vector = ... # from your embedding model index.update( id='document1#chunk2', values=new_vector, set_metadata={ "document_id": "document1", "document_title": "Introduction to Vector Databases - Revised", "chunk_number": 2, "chunk_text": "Updated second chunk content...", "document_url": "https://example.com/docs/document1", "created_at": "2024-01-15", "updated_at": "2024-02-15", "document_type": "tutorial" }, namespace='example-namespace' ) print("Updated chunk 2 successfully") ``` ### Delete chunks To [delete](/guides/manage-data/delete-data#delete-records-by-metadata) chunks of a document, use a [metadata filter expression](/guides/search/filter-by-metadata#metadata-filter-expressions) that limits the deletion appropriately: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") # Delete chunks 1 and 3 index.delete( namespace="example-namespace", filter={ "document_id": {"$eq": "document1"}, "chunk_number": {"$in": [1, 3]} } ) # Delete all chunks for a document index.delete( namespace="example-namespace", filter={ "document_id": {"$eq": "document1"} } ) ``` ### Update an entire document If you need to update most of the records in a large namespace, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) for help creating an export to enable a faster and more cost-effective approach. When the amount of chunks or ordering of chunks for a document changes, the recommended approach is to first [delete all chunks using a metadata filter](/guides/manage-data/delete-data#delete-records-by-metadata), and then [upsert](/guides/index-data/upsert-data) the new chunks: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") # Step 1: Delete all existing chunks for the document index.delete( namespace="example-namespace", filter={ "document_id": {"$eq": "document1"} } ) print("Deleted existing chunks for document1") # Step 2: Upsert the updated document chunks chunk1_vector = ... # from your embedding model chunk2_vector = ... index.upsert( namespace="example-namespace", vectors=[ { "id": "document1#chunk1", "values": chunk1_vector, "metadata": { "document_id": "document1", "document_title": "Introduction to Vector Databases - Updated Edition", "chunk_number": 1, "chunk_text": "Updated first chunk with new content...", "document_url": "https://example.com/docs/document1", "created_at": "2024-02-15", "document_type": "tutorial", "version": "2.0" } }, { "id": "document1#chunk2", "values": chunk2_vector, "metadata": { "document_id": "document1", "document_title": "Introduction to Vector Databases - Updated Edition", "chunk_number": 2, "chunk_text": "Updated second chunk with new content...", "document_url": "https://example.com/docs/document1", "created_at": "2024-02-15", "document_type": "tutorial", "version": "2.0" } } # Add more chunks as needed for the updated document ] ) print("Successfully updated document1 with new chunks") ``` ## Data freshness Pinecone is [eventually consistent](/guides/index-data/check-data-freshness), so it's possible that a write (upsert, update, or delete) followed immediately by a read (query, list, or fetch) may not return the latest version of the data. If your use case requires retrieving data immediately, consider implementing a small delay or [retry logic](/guides/production/error-handling#implement-retry-logic) after writes. ## Design for multi-tenancy Many applications have a concept of tenants—users, organizations, projects, or other groups that should only access their own data. How you model this access control significantly impacts query performance and cost. ### Use namespaces for tenant isolation The most efficient way to implement multi-tenancy is to use [namespaces](/guides/index-data/indexing-overview#namespaces) to separate data by tenant. With this approach, each tenant has their own namespace, and queries only scan that tenant's data—resulting in better performance and lower costs. For a complete implementation guide with examples across all SDKs, see [Implement multitenancy](/guides/index-data/implement-multitenancy). When you use namespaces for multi-tenancy: * **Lower query costs and faster performance**: Query cost is based on namespace size. If you have 100 tenants with 1 GB each, querying one tenant's namespace costs 1 RU and scans only 1 GB. With metadata filtering in a single namespace (100 GB total), the same query costs 100 RUs and scans all 100 GB, even though the filter narrows results. * **Natural isolation**: Reduces the risk of application bugs that could query the wrong tenant's data (for example, by passing an incorrect filter value). ### Avoid filtering by high-cardinality IDs A common anti-pattern is storing all data in a single namespace and using metadata filters to scope queries to specific users: ```python Python theme={null} # Anti-pattern: Filtering by many user IDs query_vector = [0.1, 0.2, 0.3, ...] # Your query vector results = index.query( vector=query_vector, top_k=10, filter={ "allowed_user_ids": {"$in": ["user_1", "user_2", ..., "user_10000"]} } ) ``` ```javascript JavaScript theme={null} // Anti-pattern: Filtering by many user IDs const queryVector = [0.1, 0.2, 0.3, ...]; // Your query vector const results = await index.query({ vector: queryVector, topK: 10, filter: { allowed_user_ids: { $in: ["user_1", "user_2", ..., "user_10000"] } } }); ``` ```java Java theme={null} // Anti-pattern: Filtering by many user IDs import com.google.protobuf.Struct; import com.google.protobuf.Value; import io.pinecone.clients.Index; import io.pinecone.clients.Pinecone; import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices; import java.util.Arrays; import java.util.List; Pinecone pinecone = new Pinecone.Builder("YOUR_API_KEY").build(); Index index = pinecone.getIndexConnection("your-index-name"); List queryVector = Arrays.asList(0.1f, 0.2f, 0.3f, ...); // Your query vector // Build filter with $in operator (up to 10,000 values) Struct.Builder filterBuilder = Struct.newBuilder(); Value.Builder listValueBuilder = Value.newBuilder(); listValueBuilder.getListValueBuilder() .addAllValues(Arrays.asList( Value.newBuilder().setStringValue("user_1").build(), Value.newBuilder().setStringValue("user_2").build() // ... up to 10,000 values )); filterBuilder.putFields("allowed_user_ids", Value.newBuilder() .setStructValue(Struct.newBuilder() .putFields("$in", listValueBuilder.build()) .build()) .build()); Struct filter = filterBuilder.build(); QueryResponseWithUnsignedIndices results = index.queryByVector( 10, queryVector, null, // default namespace filter ); ``` ```go Go theme={null} // Anti-pattern: Filtering by many user IDs import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v5/pinecone" "google.golang.org/protobuf/types/known/structpb" ) ctx := context.Background() clientParams := pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", } pc, err := pinecone.NewClient(clientParams) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.DescribeIndex(ctx, "your-index-name") if err != nil { log.Fatalf("Failed to describe index: %v", err) } idxConnection, err := pc.Index(pinecone.NewIndexConnParams{ Host: idx.Host, }) if err != nil { log.Fatalf("Failed to create IndexConnection: %v", err) } queryVector := []float32{0.1, 0.2, 0.3, ...} // Your query vector userIds := []interface{}{"user_1", "user_2", /* ... up to 10,000 values */} metadataMap := map[string]interface{}{ "allowed_user_ids": map[string]interface{}{ "$in": userIds, }, } filter, err := structpb.NewStruct(metadataMap) if err != nil { log.Fatalf("Failed to create filter: %v", err) } queryReq := &pinecone.QueryByVectorValuesRequest{ Vector: queryVector, TopK: 10, MetadataFilter: filter, IncludeMetadata: true, } results, err := idxConnection.QueryByVectorValues(ctx, queryReq) if err != nil { log.Fatalf("Failed to query: %v", err) } fmt.Printf("Found %d matches:\n", len(results.Matches)) for _, match := range results.Matches { fmt.Printf(" ID: %s, Score: %.4f\n", match.Vector.Id, match.Score) if match.Vector.Metadata != nil { fmt.Printf(" Metadata: %v\n", match.Vector.Metadata) } } ``` ```bash curl theme={null} # Anti-pattern: Filtering by many user IDs PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X POST "https://$INDEX_HOST/query" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "vector": [0.1, 0.2, 0.3, ...], "topK": 10, "includeMetadata": true, "filter": { "allowed_user_ids": { "$in": ["user_1", "user_2", ..., "user_10000"] } } }' ``` This approach has several drawbacks: * **Performance degradation**: Large `$in` filters increase network payload size and query latency. * **Hard limits**: Each `$in` or `$nin` operator is limited to 10,000 values. Exceeding this limit will cause the request to fail. See [Metadata filter limits](/reference/api/database-limits#metadata-filter-limits). ### Use access control groups instead of individual IDs If data must be shared across many tenants, design your access control using the smallest number of groups that describe a user's access: ```python Python theme={null} # Better: Filter by organization or role instead of individual users query_vector = [0.1, 0.2, 0.3, ...] # Your query vector results = index.query( vector=query_vector, top_k=10, filter={ "$or": [ {"organization_id": {"$eq": "org_A"}}, {"project_id": {"$eq": "project_B"}} ] } ) ``` ```javascript JavaScript theme={null} // Better: Filter by organization or role instead of individual users const queryVector = [0.1, 0.2, 0.3, ...]; // Your query vector const results = await index.query({ vector: queryVector, topK: 10, filter: { $or: [ { organization_id: { $eq: "org_A" } }, { project_id: { $eq: "project_B" } } ] } }); ``` ```java Java theme={null} // Better: Filter by organization or role instead of individual users import com.google.protobuf.Struct; import com.google.protobuf.Value; import io.pinecone.clients.Index; import io.pinecone.clients.Pinecone; import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices; import java.util.Arrays; import java.util.List; Pinecone pinecone = new Pinecone.Builder("YOUR_API_KEY").build(); Index index = pinecone.getIndexConnection("your-index-name"); List queryVector = Arrays.asList(0.1f, 0.2f, 0.3f, ...); // Your query vector // Build filter with $or operator Struct.Builder orgFilterBuilder = Struct.newBuilder(); orgFilterBuilder.putFields("organization_id", Value.newBuilder() .setStructValue(Struct.newBuilder() .putFields("$eq", Value.newBuilder() .setStringValue("org_A") .build()) .build()) .build()); Struct.Builder projectFilterBuilder = Struct.newBuilder(); projectFilterBuilder.putFields("project_id", Value.newBuilder() .setStructValue(Struct.newBuilder() .putFields("$eq", Value.newBuilder() .setStringValue("project_B") .build()) .build()) .build()); Struct.Builder orFilterBuilder = Struct.newBuilder(); orFilterBuilder.putFields("$or", Value.newBuilder() .getListValueBuilder() .addValues(Value.newBuilder().setStructValue(orgFilterBuilder.build()).build()) .addValues(Value.newBuilder().setStructValue(projectFilterBuilder.build()).build()) .build()); QueryResponseWithUnsignedIndices results = index.queryByVector( 10, queryVector, null, // default namespace orFilterBuilder.build(), false, // includeValues true // includeMetadata ); ``` ```go Go theme={null} // Better: Filter by organization or role instead of individual users import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v5/pinecone" "google.golang.org/protobuf/types/known/structpb" ) ctx := context.Background() clientParams := pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", } pc, err := pinecone.NewClient(clientParams) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.DescribeIndex(ctx, "your-index-name") if err != nil { log.Fatalf("Failed to describe index: %v", err) } idxConnection, err := pc.Index(pinecone.NewIndexConnParams{ Host: idx.Host, }) if err != nil { log.Fatalf("Failed to create IndexConnection: %v", err) } queryVector := []float32{0.1, 0.2, 0.3, ...} // Your query vector metadataMap := map[string]interface{}{ "$or": []interface{}{ map[string]interface{}{ "organization_id": map[string]interface{}{ "$eq": "org_A", }, }, map[string]interface{}{ "project_id": map[string]interface{}{ "$eq": "project_B", }, }, }, } filter, err := structpb.NewStruct(metadataMap) if err != nil { log.Fatalf("Failed to create filter: %v", err) } queryReq := &pinecone.QueryByVectorValuesRequest{ Vector: queryVector, TopK: 10, MetadataFilter: filter, IncludeMetadata: true, } results, err := idxConnection.QueryByVectorValues(ctx, queryReq) if err != nil { log.Fatalf("Failed to query: %v", err) } fmt.Printf("Found %d matches:\n", len(results.Matches)) for _, match := range results.Matches { fmt.Printf(" ID: %s, Score: %.4f\n", match.Vector.Id, match.Score) if match.Vector.Metadata != nil { fmt.Printf(" Metadata: %v\n", match.Vector.Metadata) } } ``` ```bash curl theme={null} # Better: Filter by organization or role instead of individual users PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X POST "https://$INDEX_HOST/query" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "vector": [0.1, 0.2, 0.3, ...], "topK": 10, "includeMetadata": true, "filter": { "$or": [ {"organization_id": {"$eq": "org_A"}}, {"project_id": {"$eq": "project_B"}} ] } }' ``` Instead of passing thousands of user IDs, this filter uses only 2 group identifiers to achieve the same access control. ### Multitenancy patterns The following table provides general guidelines for choosing a multitenancy approach. Evaluate your specific use case, access patterns, and requirements to determine the best fit for your application. | Data pattern | Recommended approach | Query cost | Performance | | :---------------------------------------- | :-------------------------------------------------------------------- | :------------------------------------- | :---------- | | Each tenant's data is completely separate | One index, one namespace per tenant | Lowest (scans only tenant namespace) | Fastest | | Large tenants with many sub-groups | One index per large tenant, namespaces for sub-groups | Low (scans only sub-group namespace) | Fast | | Data shared across tenants | One index, shared namespace, filter by group IDs (org, project, role) | Higher (scans entire shared namespace) | Slower | Avoid filtering by large lists of individual user IDs (for example, `{"user_id": {"$in": ["user_1", "user_2", ..., "user_10000"]}}`). This approach has the following drawbacks: * Hard limits: Each `$in` or `$nin` operator is limited to 10,000 values. Exceeding this limit will cause requests to fail. * Performance: Large filters increase query latency. * Higher costs: You pay for scanning the entire shared namespace, even though the filter narrows results. Instead, consider these alternatives: * Use one namespace per tenant (see row 1 in the table above). * Filter by broader groups like organization, project, or role rather than individual user IDs (see row 3 in the table above). * Retrieve a larger top K without filtering (for example, top 1000), then filter the results client-side. For a complete step-by-step implementation guide, see [Implement multitenancy](/guides/index-data/implement-multitenancy). # Dedicated Read Nodes Source: https://docs.pinecone.io/guides/index-data/dedicated-read-nodes Dedicated read nodes use provisioned hardware for read operations, providing predictable, low-latency performance at high query volumes. ## Overview Pinecone indexes built on dedicated read nodes use provisioned read hardware to provide predictable, consistent performance at sustained, high query volumes. They're designed for large-scale vector workloads such as semantic search, recommendation engines, and mission-critical services. Dedicated read nodes differ from on-demand indexes in how they handle read operations. While on-demand indexes use shared, multi-tenant capacity for reads, dedicated read nodes provision exclusive hardware for reads—memory, local SSDs, and compute. Both index types use Pinecone's serverless infrastructure for writes and storage. When you create a dedicated read nodes index, Pinecone provisions resources based on your choice of [node type](#node-types), number of [shards](#shards), and number of [replicas](#replicas). These resources include local SSDs and memory that cache all your index data, and provide dedicated query executors to handle read operations (query, fetch, list). This architecture eliminates cold starts and ensures consistent low-latency performance, even under heavy load. Dedicated read nodes support dense, sparse, hybrid, and [full-text search](/guides/search/full-text-search) indexes, giving you flexibility in your search and retrieval strategy. Because storage (shards) and compute (replicas) scale independently, you can optimize for your specific workload characteristics. ## On-demand vs dedicated On-demand indexes and dedicated read nodes are both built on Pinecone's serverless infrastructure. They use the same write path, storage layer, and data operations API. However, every dedicated read nodes index has isolated hardware for read operations (query, fetch, list), allowing these operations to run on dedicated query executors. This affects performance, cost, and how you scale: | Feature | On-demand | Dedicated read nodes | | :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Read infrastructure** | Multi-tenant compute resources shared across customers | Isolated, provisioned query executors dedicated to your index | | **Read costs** | Pay per [read unit](/guides/manage-cost/understanding-cost#serverless-indexes) (1 RU per 1 GB of namespace size per query, minimum 0.25 RU) | Fixed hourly rate for read capacity based on node type, shards, and replicas | | **Other costs** | [Storage](/guides/manage-cost/understanding-cost#storage) and [write](/guides/manage-cost/understanding-cost#write-units) costs based on usage | [Storage](/guides/manage-cost/understanding-cost#storage) and [write](/guides/manage-cost/understanding-cost#write-units) costs based on usage (same as on-demand) | | **Caching** | Best-effort; frequently accessed data is cached, but cold queries fetch from object storage | Guaranteed; all index data always warm in memory and on local SSDs | | **Read rate limits** | [2,000 RUs/second per index (adjustable)](/reference/api/database-limits#rate-limits) | No read rate limits (only bounded by CPU capacity) | | **Scaling** | Automatic; Pinecone handles capacity | Manual; add [shards](#shards) for storage, add [replicas](#replicas) for throughput | | **Query-time tuning** | Parameters accepted but have no effect | Optional [`scan_factor` and `max_candidates`](#query-time-search-parameters) to trade recall for lower latency and higher throughput | | **Best for** | Variable workloads, multi-tenant applications with many namespaces, low to moderate query rates | Sustained high query rates, large single-namespace workloads, predictable performance and cost | ## When to use dedicated read nodes Dedicated read nodes are ideal for workloads with millions to billions of records and predictable query rates. They provide performance and cost benefits compared to on-demand for high-throughput workloads, and may be required when your workload exceeds on-demand rate limits. There's no universal formula for choosing between on-demand and dedicated read nodes—performance and cost vary by workload (vector dimensionality, metadata filtering, and query patterns). Consider the following factors when making your decision: With dedicated read nodes, you allocate dedicated read hardware for your index, and your data is cached in memory and on local SSDs. This provides: * Consistent low latency under heavy load. * No cold starts (fetching data from object storage). * Performance isolation from other workloads. * Linear scaling by adding replicas. * Predictable costs based on fixed hourly rates for provisioned hardware. If predictable performance and cost are critical for your application, dedicated read nodes may be a better fit than on-demand. On-demand indexes are subject to [read unit rate limits](/reference/api/database-limits#rate-limits) (default: 2,000 RUs/second per index). A high query volume on a large index can exceed these limits. For example, a 15 GB namespace at 150 QPS requires approximately 2,250 RUs/second (`15 RUs per query × 150 QPS`), which exceeds the default rate limit. Dedicated read nodes have no read rate limits and provide dedicated capacity for predictable QPS without throttling (bounded only by CPU capacity), making them better suited for high-throughput workloads. Recommendation engines for use cases such as e-commerce and media require very high throughput and low latency to maintain positive user experiences. Dedicated read nodes are purpose-built for these use cases, providing: * Consistent performance for thousands of queries per second * Low latency for real-time recommendations * Scalability to billion-vector datasets * No performance degradation during traffic spikes Similar requirements apply to other real-time use cases like semantic search at scale, personalization engines, and mission-critical services with strict performance SLOs. Dedicated read nodes indexes support only a single namespace. If your application requires multiple namespaces, on-demand is a better fit. Multi-namespace support is coming soon. For early access, [contact us](https://www.pinecone.io/contact/). On-demand indexes are better suited for workloads with unpredictable or highly variable traffic patterns. For example: * RAG systems with variable query volumes * Agentic applications with sporadic usage * Prototypes and development environments with intermittent activity * Scheduled jobs with infrequent, batch-style queries Additionally, on-demand is better for indexes with many namespaces, even if you have high query volumes. Dedicated read nodes currently only support single-namespace indexes, so multi-tenant applications requiring namespace-based isolation should use on-demand until multi-namespace support is available. For these scenarios, on-demand's elasticity and usage-based pricing provide better cost efficiency than provisioning dedicated capacity. Dedicated read nodes **can** handle predictable traffic spikes efficiently if you scale replicas proactively via the API. For example, you can provision extra replicas before a scheduled email campaign and scale back down afterward. Auto-scaling will be available in a future release. On-demand and dedicated read nodes have different cost structures. The key difference is read costs: on-demand uses usage-based pricing, while dedicated read nodes use a fixed hourly rate based on provisioned hardware. Write and storage costs are usage-based for both modes. Dedicated read nodes become cost-effective when you have predictable, sustained query volumes that make full use of your provisioned capacity. With unpredictable or low query volumes, you pay hourly rates even when your machines sit idle, making on-demand's usage-based pricing more economical. For detailed cost information, comparison tables, and estimation tools, see the [Cost](#cost) section of this guide. Performance depends on your specific workload — index size, vector dimensionality, metadata filtering, query patterns, throughput requirements, and latency requirements. Testing is the only way to know for sure whether dedicated read nodes are right for your scenario. For a step-by-step guide to testing, see [Test your workload](#test-your-workload). If you need guidance choosing a capacity mode (on-demand or dedicated read nodes) or sizing your index configuration, [contact us](https://www.pinecone.io/contact/). ## Key concepts Before creating a dedicated read nodes index, understand the configuration options that determine capacity and performance. ### Node types A node is the basic unit of compute and cache storage capacity for a dedicated read nodes index. Each shard runs on one node, so the node type you choose determines the performance characteristics and cost of your index. The total number of nodes in your index is calculated as `shards × replicas`. For example, an index with two shards and two replicas uses four nodes. There are two node types: `b1` and `t1`. Both are suitable for large-scale and demanding workloads, but they differ in processing power and memory capacity, and they cache different data. | | **b1 (Balanced)** | **t1 (Performance)** | | -------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | **Memory caching** | Vector index stored in memory | Vector index + vector projections cached in memory | | **Use case** | Predictable performance for sustained query rates with balanced cost efficiency | Highest performance for the most demanding workloads with extreme query volumes and strict latency requirements | | **Storage** | 250 GB per shard | 250 GB per shard | | **Compute & memory** | Base-level compute and memory resources | \~4x more compute and memory than `b1` | | **Cost** | Lower-cost option | \~3x the cost of `b1` | Consider using `t1` nodes if your performance requirements are not met by `b1` nodes, or if `t1` nodes are more cost-effective than `b1` nodes for your workload. When choosing a node type, remember that: * Both types of nodes provide 250 GB of storage per shard. The difference is in compute and memory, which affects query performance. * Because `t1` nodes cache more data in memory than `b1` nodes, an index may require more shards on `t1` than on `b1` (for the same data). * You can [change node types](#change-node-types) after creating your index. ### Shards Shards determine the storage capacity of an index. Each shard provides 250 GB of storage, and data is split across all the shards in an index. To respond to a query, the index gathers data from all shards as needed. To determine how many shards you need, [calculate your index size](#calculate-the-size-of-your-index) and then [calculate the number of shards](#number-of-shards). It's your responsibility to allocate enough shards to accommodate the size of your index. If your index exceeds the capacity of its shards, write operations (upsert, update, delete) are blocked, but read operations continue to work normally. ### Replicas Replicas multiply the compute resources and data of an index, allowing for higher query throughput and availability. Each replica is a complete copy of your index data and has its own dedicated compute resources. * Throughput scales approximately linearly with replicas. For example, if one replica handles 50 QPS at your target latency, two replicas should handle approximately 100 QPS. * You can scale replicas up or down with no downtime using the API. See [Add or remove replicas](#add-or-remove-replicas). * Minimum: 0 replicas ([pauses the index](#pause-an-index)). * For high availability, use at least two replicas. The recommended approach is to allocate `n+1` replicas where `n` is your minimum for throughput. Pinecone distributes replicas across availability zones (up to three per region), so if one zone fails, remaining replicas continue serving queries. To determine how many replicas you need, [test your workload](#test-your-workload) and then [calculate the number of replicas](#number-of-replicas). Actual performance varies based on workload characteristics (query complexity, vector dimensions, metadata characteristics), [metadata filter](/guides/search/filter-by-metadata) selectivity, and [node type](#node-types) (`b1` vs `t1`). Always test with your specific workload. ### Index fullness Index fullness measures how much of your index's allocated capacity is being used. To ensure predictable performance, dedicated read nodes cache your data in memory and on local SSD. * You can use Pinecone's API to [check index fullness](#monitor-index-fullness). There are three metrics to monitor: `memoryFullness`, `storageFullness`, and `indexFullness`. `indexFullness` is the maximum of `memoryFullness` and `storageFullness`. * Usually, storage fills up first. However, memory can be the limiting factor when you have `b1` nodes with many low-dimension vectors, or when you have `t1` nodes with high-dimension vectors and lots of metadata. * Monitor fullness regularly and [add shards](#add-or-remove-shards) before your index reaches capacity. When `indexFullness` reaches 1.0 (100%), write operations (upsert, update, delete) are blocked, but read operations continue to work normally. Add shards when [index fullness](#index-fullness) reaches 70-80%, especially if you expect continued growth. Adding shards reduces storage fullness (index data is spread across shards, so each stores less) and memory fullness (with less data per shard, there's less to cache in memory), helping you avoid write failures. ## Query-time search parameters Dedicated read nodes support two optional query-time parameters — `scan_factor` and `max_candidates` — that let you trade off recall (search quality) for lower latency and higher throughput. By default, queries use internal heuristics that favor recall. If your application is latency-sensitive or needs higher QPS, you can tune these parameters to reduce the work done per query — or increase them for higher recall. These parameters only take effect on dedicated read nodes indexes with dense vectors. On on-demand indexes, the parameters are accepted but have no effect. On indexes that store only sparse vectors, specifying either parameter returns an error. Using these parameters requires API version `2025-10` or later. ### How scan\_factor and max\_candidates work Dense vector search on dedicated read nodes uses a two-stage pipeline: 1. **Scanning** — controlled by `scan_factor`. For IVF-based indexes, the system scans a fraction of partitions determined by `scan_factor / sqrt(num_partitions)`. A lower `scan_factor` scans fewer partitions, producing fewer candidates faster. This parameter only affects IVF-based slabs; for other index architectures (e.g., smaller indexes using flat search), `scan_factor` has no effect. 2. **Reranking** — controlled by `max_candidates`. The top candidates from the scanning stage are reranked by computing exact distances. More reranking improves recall but increases latency. This parameter applies to all index architectures. The two parameters affect different stages and their effects are additive — you can set both to optimize each stage independently. | Parameter | Type | Range | Default | Description | | :------------------- | :------ | :----------------------------------- | :-------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- | | **`scan_factor`** | Float | 0.5–4.0 | 4.0 | Controls how much of the IVF index is scanned to find vector candidates. Lower values scan fewer partitions and return results faster. | | **`max_candidates`** | Integer | Your query's `top_k` value – 100,000 | 2500 (see [default behavior](#default-max_candidates-behavior)) | Maximum number of candidate vectors to rerank with exact distance computation. Higher values improve recall; lower values improve latency. | You can set one or both per query. Omitting both preserves the current default behavior, so existing applications are unaffected. #### Default `max_candidates` behavior When `max_candidates` is not set, the system calculates an effective value using the following formula: * If `top_k` \<= 1000: `min(top_k * 10, 1000)` * If `top_k` > 1000: `top_k` * Then, a floor of 2500 is applied (the effective value is at least 2500) For most queries (where `top_k` \<= 2500), the effective default is **2500**. This is not the maximum possible value — you can raise `max_candidates` (up to 100,000) to increase recall, or lower it (down to your query's `top_k`) to reduce latency. When you explicitly set `max_candidates`, the value you provide is used directly, bypassing the formula and the floor. ### Impact on recall and performance Lower `scan_factor` or `max_candidates` values reduce the work done per query, which improves latency and throughput but may reduce recall. The tables below summarize benchmarked behavior on a 2.68M-vector index (1536 dimensions, cosine similarity). Actual results are dataset-dependent. #### `scan_factor` benchmarks Starting from the default (4.0), lowering `scan_factor` reduces the fraction of IVF partitions scanned: | scan\_factor | Approximate recall (p50) | Relative throughput | | :------------ | :----------------------- | :------------------ | | 4.0 (default) | \~96% | 1x (baseline) | | 2.0 | \~94% | \~1.5x | | 1.0 | \~91% | \~2x | | 0.5 | \~84% | \~4x | Testing shows that lower `scan_factor` values can reduce p50 and p99 latency by 30–50% or more. #### Tuning `max_candidates` Higher `max_candidates` improves recall by reranking more candidates but increases latency and reduces throughput; lower values favor speed. For guidance on choosing values, see [Tuning guidance](#tuning-guidance). We recommend benchmarking on your own dataset and workload to find the right balance—use the [Test your workload](#test-your-workload) process to validate latency and recall. ### Tuning guidance Start with the defaults and adjust based on your workload requirements: * **To optimize for throughput/latency:** Lower `scan_factor` first (from the default of 4.0). This has the most impact on IVF-based indexes. If you need further improvement, lower `max_candidates` below the default of 2500 (down to your query's `top_k` value). * **To optimize for recall:** Raise `max_candidates` above the default of 2500 (up to 100,000). This reranks more candidate vectors at the cost of higher latency. **Trade-offs to consider:** * **Adjust one parameter at a time.** `scan_factor` controls the scanning stage (IVF only) and `max_candidates` controls the reranking stage (all index types). Tuning them independently makes it easier to isolate the effect. * **Safe defaults:** Omitting both parameters preserves existing behavior. There is no risk to existing queries. * **Cost reduction:** By achieving higher throughput per node, you may be able to serve the same query rate with fewer replicas. ### Behavior by vector type | Index / query type | Behavior | | :----------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Dense vectors, dense query** | `scan_factor` and `max_candidates` apply normally. | | **Dense vectors, hybrid query (dense + sparse)** | Both parameters apply to the dense component only; the sparse component is unaffected. | | **Sparse vectors only** | Specifying `scan_factor` or `max_candidates` returns an error. | | **On-demand index** | Both parameters are accepted but have no effect on search behavior. You can use the same query code against on-demand (e.g., for development) and dedicated read nodes (for production) without modification. | ### API and SDK examples Both parameters are optional fields on the `POST /query` request. ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="YOUR_INDEX_HOST" curl -X POST "https://$INDEX_HOST/query" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "namespace": "example-namespace", "topK": 10, "vector": [0.1, 0.2, 0.3], "scanFactor": 1.0, "maxCandidates": 1000 }' ``` ```python Python theme={null} # Both parameters — balanced recall and latency index.query( namespace="example-namespace", vector=[0.1, 0.2, 0.3], top_k=10, scan_factor=1.0, max_candidates=1000 ) # scan_factor only — faster queries, lower recall index.query( namespace="example-namespace", vector=[0.1, 0.2, 0.3], top_k=10, scan_factor=0.5 ) # Omit both for maximum recall (default behavior) index.query( namespace="example-namespace", vector=[0.1, 0.2, 0.3], top_k=10 ) ``` ```typescript TypeScript theme={null} // Both parameters — balanced recall and latency await index.query({ namespace: "example-namespace", vector: [0.1, 0.2, 0.3], topK: 10, scanFactor: 1.0, maxCandidates: 1000 }); // scan_factor only — faster queries, lower recall await index.query({ namespace: "example-namespace", vector: [0.1, 0.2, 0.3], topK: 10, scanFactor: 0.5 }); ``` **Validation errors:** | Condition | Error message | | :-------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- | | API version earlier than `2025-10` | `scan_factor and max_candidates parameters require API version 2025-10 or later` | | `scan_factor` outside 0.5–4.0 | `scan_factor must be between 0.5 and 4.0, got {value}` | | `max_candidates` below your query's `top_k` or above 100,000 | `max_candidates must be between {top_k} (top_k) and {max}, got {value}` | | Used on an index that stores only sparse vectors (API error text says "sparse indexes") | `scan_factor and max_candidates parameters are not supported for sparse indexes` | `scan_factor` and `max_candidates` do not affect billing. Read costs for dedicated read nodes are based on provisioned capacity (node type, shards, and replicas), not per-query effort. By tuning these parameters to achieve higher throughput, you may be able to serve the same query rate with fewer provisioned replicas, reducing your overall cost. ## Test your workload To choose between on-demand and dedicated read nodes, or to optimize your dedicated read nodes configuration, test with your actual workload. Performance varies based on factors such as the size of your index,vector dimensionality, metadata characteristics, and query patterns. [Calculate the size of your index](#calculate-the-size-of-your-index) to determine how many shards it requires. [Create a dedicated read nodes index](#create-a-dedicated-read-nodes-index) with representative data for your workload. You'll use this index for testing. If you don't restore your test index from a backup, you can [upsert](/guides/index-data/upsert-data) or [import](/guides/index-data/import-data) your data. If your test index is on-demand, [migrate it to dedicated read nodes](#migrate-to-dedicated-read-nodes). To start, use a single `b1` replica. Don't migrate your production index yet. At this point, you're just testing your workload. Run realistic query patterns against your test index, gradually increasing QPS. For example, start at 10 QPS for about 30 minutes, then increase by 10 QPS increments while monitoring latency. Identify the QPS where latency exceeds your target threshold. Throughput scales approximately linearly with replicas. For example, if one replica handles 50 QPS at your target latency, two replicas should handle approximately 100 QPS. However, performance can vary based on metadata filter selectivity. To calculate the number of replicas required for your target QPS, use this formula, rounding up: ``` Minimum replicas = (Required QPS) / (QPS per replica) ``` For more information, see [Number of replicas](#number-of-replicas). To meet your performance and cost goals, adjust your configuration as needed and re-test: * [Add or remove shards](#add-or-remove-shards) for storage capacity * [Add or remove replicas](#add-or-remove-replicas) for throughput * [Change node types](#change-node-types) for different performance characteristics Continue iterating until you meet your requirements with room for growth. ## Calculate the size of your index To determine how many [shards](#shards) your index requires, calculate your index size and then use the formula in the [section](#number-of-shards) below. ### Index size A record can include a dense vector, a sparse vector, or both. Use the formula that matches your data to calculate total size:
An [index of dense vectors](/guides/index-data/indexing-overview#indexes-with-dense-vectors) contains records with one dense vector each. Records can also contain sparse vectors (when the index metric is set to `dotproduct`), which can be useful for [hybrid search](/guides/search/hybrid-search#use-a-single-index-for-dense-and-sparse-vectors). To learn how to calculate size in that case, see [Index with both dense and sparse vectors](#index-with-both-dense-and-sparse-vectors). **Calculate size (assuming no sparse vectors)** ``` Index size = Number of records × ( ID size + Metadata size + Dense vector dimensions × 4 bytes ) ``` Where: * `ID size` and `Metadata size` are measured in bytes, averaged across all records. * Each `Dense vector dimension` uses 4 bytes. **Example calculations** These examples assume 8-byte IDs: | Records | Dense vector dimensions | Avg metadata size | Index size | | :--------- | :---------------------- | :---------------- | :--------- | | 500,000 | 768 | 500 bytes | 1.79 GB | | 1,000,000 | 1536 | 1,000 bytes | 7.15 GB | | 5,000,000 | 1024 | 15,000 bytes | 95.5 GB | | 10,000,000 | 1536 | 1,000 bytes | 71.5 GB | Example: 500,000 records × (8-byte ID + (768 dense vector dimensions × 4 bytes) + 500 bytes of metadata) = 1.79 GB An [index of sparse vectors](/guides/index-data/indexing-overview#indexes-with-sparse-vectors) contains records with one sparse vector each. **Calculate size** ``` Index size = Number of records × ( ID size + Metadata size + Number of non-zero sparse values × 8 bytes ) ``` Where: * `ID size` and `Metadata size` are measured in bytes, averaged across all records. * `Number of non-zero sparse values`: Average number across all records. To find the count for a single record, check the length of the sparse vector's `indices` or `values` array. Each non-zero value uses 8 bytes. **Example calculations** These examples assume 8-byte IDs: | Records | Avg number of non-zero sparse values | Avg metadata size | Index size | | :--------- | :----------------------------------- | :---------------- | :--------- | | 500,000 | 10 | 500 bytes | 0.29 GB | | 1,000,000 | 50 | 1,000 bytes | 1.41 GB | | 5,000,000 | 100 | 15,000 bytes | 79.0 GB | | 10,000,000 | 50 | 1,000 bytes | 14.1 GB | Example: 500,000 records × (8-byte ID + (10 non-zero sparse values × 8 bytes) + 500 bytes of metadata) = 0.29 GB An [index with both dense and sparse vectors](/guides/search/hybrid-search#use-a-single-index-for-dense-and-sparse-vectors) contains records that each have one dense vector and an optional sparse vector. **Calculate size** ``` Index size = Number of records × ( ID size + Metadata size + Dense vector dimensions × 4 bytes + Number of non-zero sparse values × 8 bytes ) ``` Where: * `ID size` and `Metadata size` are measured in bytes, averaged across all records. * Each `Dense vector dimension` uses 4 bytes. * `Number of non-zero sparse values`: Average number across all records, including those without sparse vectors. To find the count for a single record, check the length of the sparse vector's `indices` or `values` array. Each non-zero value uses 8 bytes. **Example calculations** These examples assume 8-byte IDs: | Records | Dense vector dimensions | Avg number of non-zero sparse values | Avg metadata size | Index size | | :--------- | :---------------------- | :----------------------------------- | :---------------- | :--------- | | 500,000 | 768 | 10 | 500 bytes | 1.83 GB | | 1,000,000 | 1536 | 50 | 1,000 bytes | 7.54 GB | | 5,000,000 | 1024 | 100 | 15,000 bytes | 99.5 GB | | 10,000,000 | 1536 | 50 | 1,000 bytes | 75.4 GB | Example: 500,000 records × (8-byte ID + (768 dense vector dimensions × 4 bytes) + (10 non-zero sparse values × 8 bytes) + 500 bytes of metadata) = 1.83 GB
### Number of shards To calculate the number of shards your index requires, divide the size of your index by 250 GB and round up: ``` Minimum shards = (Index size) / (250 GB per shard) ``` To maintain optimal performance, provision additional shards to keep your index at 70-80% capacity. For example, a 500 GB index should have three shards (750 GB capacity = 67% full), not two shards (500 GB capacity = 100% full). **Example shard calculations** | Index size | Minimum shards | Recommended shards | | :----------- | :------------------- | :------------------- | | **\~71 GB** | 1 (250 GB; 28% full) | 1 (250 GB; 28% full) | | **\~300 GB** | 2 (500 GB; 60% full) | 2 (500 GB; 60% full) | | **\~400 GB** | 2 (500 GB; 80% full) | 3 (750 GB; 53% full) | **Other considerations** * Every index must have at least one shard. However, you can [pause an index](#pause-an-index) by reducing its replicas to 0. * After you've created your index, [monitor its fullness](#monitor-index-fullness). When your index approaches capacity, you can [add shards](#add-or-remove-shards). Add shards when [index fullness](#index-fullness) reaches 70-80%, especially if you expect continued growth. Adding shards reduces storage fullness (index data is spread across shards, so each stores less) and memory fullness (with less data per shard, there's less to cache in memory), helping you avoid write failures. ### Number of replicas To calculate the number of replicas your index requires, first [test your workload](#test-your-workload) to find the QPS a single replica can handle at your target latency. Then, use this formula, and round up: ``` Minimum replicas = (Required QPS) / (QPS per replica) ``` For example, if one replica handles 50 QPS at your target latency and you need 150 QPS, you need three replicas. **Other considerations** * Throughput scales approximately linearly with replicas, but performance can vary based on metadata filter selectivity. * For high availability, allocate `n+1` replicas where `n` is your minimum for throughput. Pinecone distributes replicas across availability zones. ## Create a dedicated read nodes index You can create a dedicated read nodes index from scratch or from a backup of an existing index. ### From scratch To create a new dedicated read nodes index from scratch, call [Create an index](/reference/api/2025-10/control-plane/create_index). In the request body, in the `spec.serverless.read_capacity` object, set the following fields: | Field | Value | Notes | | :------------------------------ | :----------------------------------------------- | :----------------------------------------------------- | | **`mode`** | `Dedicated` | | | **`dedicated.node_type`** | `b1` or `t1` | See [node types](#node-types) | | **`dedicated.scaling`** | `Manual` | Currently the only option | | **`dedicated.manual.shards`** | Number of [shards](#number-of-shards) needed | Minimum 1 shard; each shard provides 250 GB of storage | | **`dedicated.manual.replicas`** | Number of [replicas](#number-of-replicas) needed | Minimum 0 (this [pauses](#pause-an-index) the index) | To learn how to determine the number of shards and replicas your index requires, see [Calculate the size of your index](#calculate-the-size-of-your-index). **Example** ```bash curl expandable theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -X POST "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "example-dedicated-index", "dimension": 1024, "metric": "cosine", "deletion_protection": "enabled", "tags": { "environment": "production" }, "vector_type": "dense", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 2, "replicas": 1 } } } } } }' ``` Example response: ```jsonc curl expandable theme={null} { "name": "example-dedicated-index", "vector_type": "dense", "metric": "cosine", "dimension": 1024, "status": { "ready": false, "state": "Initializing" }, "host": "example-dedicated-index-1c6ab6aa.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 2, // <---- desired state "replicas": 1 } }, "status": { "state": "Migrating", "current_shards": null, // <---- current state "current_replicas": null } } } }, "deletion_protection": "enabled", "tags": { "environment": "production" } } ``` The response includes two status fields: | Field | Description | | :----------------------------------------------- | :------------------------------------------------------------------------- | | **`status.state`** | Overall index status (for example, `Initializing`, `Ready`, `Terminating`) | | **`spec.serverless.read_capacity.status.state`** | Read capacity status (`Migrating`, `Scaling`, `Ready`, `Error`) | When creating a dedicated read nodes index, `status.state` transitions to `Ready` as soon as the index is ready for reads and writes. However, `spec.serverless.read_capacity.status.state` remains `Migrating` until the index scales to its full read capacity, at which point it transitions to `Ready`. After creating the index, [upsert](/guides/index-data/upsert-data) or [import](/guides/index-data/import-data) your data. To upsert and search with text instead of vectors, you can configure your index to use a [hosted embedding model](/guides/index-data/create-an-index#embedding-models). Call [Configure an index](/reference/api/2025-10/control-plane/configure_index) and specify the `embed` object in the request body. ### From a backup To create a dedicated read nodes index from a backup: 1. [Restore the backup](/guides/manage-data/restore-an-index). This creates a new on-demand index with the same data as the original. 2. If the restored index has multiple namespaces, [delete](/reference/api/latest/data-plane/deletenamespace) all of them except the one you want to keep. Dedicated read nodes currently only support [one namespace](#namespace-limits). 3. [Migrate the index to dedicated read nodes](#migrate-to-dedicated-read-nodes). ## Migrate to dedicated read nodes ### From a pod-based index You cannot migrate a pod-based index directly to dedicated read nodes. First complete [Migrate a pod-based index to serverless](/guides/indexes/pods/migrate-a-pod-based-index-to-serverless), which creates a new on-demand index with your data. If that index has multiple namespaces, consolidate to one namespace, or plan a different architecture. Dedicated read nodes currently support only a [single namespace](#namespace-limits). ### From an on-demand (serverless) index To migrate an existing on-demand index to dedicated read nodes—including one you created by [migrating from pods](#from-a-pod-based-index)—follow these steps: [Create a backup](/guides/manage-data/back-up-an-index) of your index. If you later find that on-demand is preferable, you can restore the backup to a new on-demand index or [contact support](https://app.pinecone.io/organizations/-/settings/support/ticket) to migrate back. If your index has multiple namespaces, [delete](/reference/api/latest/data-plane/deletenamespace) all of them except the one you want to keep. Dedicated read nodes currently only support a [single namespace](#namespace-limits). If this is a production index, be sure to make a [backup](/guides/manage-data/back-up-an-index) before deleting namespaces. Or, if you need multiple namespaces, [contact support](https://app.pinecone.io/organizations/-/settings/support/ticket) to discuss early access to multi-namespace support for dedicated read nodes. [Calculate your index size](#index-size) to determine how many [shards](#number-of-shards) you need. To migrate the index, call [Configure an index](/reference/api/2025-10/control-plane/configure_index). In the request body, in the `spec.serverless.read_capacity` object, set the following fields: | Field | Value | Notes | | :------------------------------ | :----------------------------------------------- | :----------------------------------------------------- | | **`mode`** | `Dedicated` | | | **`dedicated.node_type`** | `b1` or `t1` | See [node types](#node-types) | | **`dedicated.scaling`** | `Manual` | Currently the only option | | **`dedicated.manual.shards`** | Number of [shards](#number-of-shards) needed | Minimum 1 shard; each shard provides 250 GB of storage | | **`dedicated.manual.replicas`** | Number of [replicas](#number-of-replicas) needed | Minimum 0 (this [pauses](#pause-an-index) the index) | **Example** This example migrates an index to dedicated read nodes using `b1` nodes, one shard, and one replica: ```bash curl expandable theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="YOUR_INDEX_NAME" curl -X PATCH "https://api.pinecone.io/indexes/$INDEX_NAME" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "spec": { "serverless": { "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 1, "replicas": 1 } } } } } }' ``` Example response: ```jsonc curl expandable theme={null} { "name": "example-index-to-migrate", "vector_type": "dense", "metric": "cosine", "dimension": 1024, "status": { "ready": true, "state": "Ready" }, "host": "example-index-to-migrate-1c6ab6aa.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 1, // <---- desired state "replicas": 1 } }, "status": { "state": "Migrating", "current_shards": null, //<---- current state "current_replicas": null } } } }, "deletion_protection": "disabled", "tags": null, "embed": { "model": "llama-text-embed-v2", "field_map": { "text": "text" }, "dimension": 1024, "metric": "cosine", "write_parameters": { "dimension": 1024, "input_type": "passage", "truncate": "END" }, "read_parameters": { "dimension": 1024, "input_type": "query", "truncate": "END" }, "vector_type": "dense" } } ``` The response includes two status fields: | Field | Description | | :----------------------------------------------- | :------------------------------------------------------------------------- | | **`status.state`** | Overall index status (for example, `Initializing`, `Ready`, `Terminating`) | | **`spec.serverless.read_capacity.status.state`** | Read capacity status (`Migrating`, `Scaling`, `Ready`, `Error`) | If `status.state` is set to `Error`, the allocated number of shards was insufficient for the size of the index. Try again, adding more shards as needed. [Monitor](#check-the-status-of-a-change) the status of the migration. When the migration is complete, `spec.serverless.read_capacity.status.state` is `Ready`. After migrating, monitor your index performance to verify that it meets expectations. ## Manage your index The following sections describe how to manage a dedicated read nodes index using version `2025-10` of the Pinecone API. To upsert and search with text instead of vectors, you can configure your index to use a [hosted embedding model](/guides/index-data/create-an-index#embedding-models). To do this, call [Configure an index](/reference/api/2025-10/control-plane/configure_index) and provide an `embed` object in the request body. In this object: * For the `text` field, specify the name of the field in your data that contains the text to be embedded. * Specify a model whose dimension requirements match the dimensions of your index. **Example** Example request: ```bash curl expandable theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="YOUR_INDEX_NAME" curl -X PATCH "https://api.pinecone.io/indexes/$INDEX_NAME" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "embed": { "field_map": { "text": "chunk_text" }, "model": "llama-text-embed-v2", "read_parameters": { "input_type": "query", "truncate": "NONE" }, "write_parameters": { "input_type": "passage" } } }' ``` Example response: ```json curl expandable theme={null} { "name": "example-dedicated-index", "vector_type": "dense", "metric": "cosine", "dimension": 1024, "status": { "ready": true, "state": "Ready" }, "host": "example-dedicated-index-1c6ab6aa.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 2, "replicas": 1 } }, "status": { "state": "Ready", "current_shards": 2, "current_replicas": 1 } } } }, "deletion_protection": "enabled", "tags": { "environment": "testing" }, "embed": { "model": "llama-text-embed-v2", "field_map": { "text": "chunk_text" }, "dimension": 1024, "metric": "cosine", "write_parameters": { "dimension": 1024, "input_type": "passage", "truncate": "END" }, "read_parameters": { "dimension": 1024, "input_type": "query", "truncate": "NONE" }, "vector_type": "dense" } } ``` You can also create a dedicated read nodes index when calling [Create an index with integrated embedding](/reference/api/2025-10/control-plane/create_for_model). In the request body, use the `read_capacity` object to configure node type, shards, and replicas for dedicated read nodes. To check [index fullness](#index-fullness), call [Get index stats](/reference/api/2025-10/data-plane/describeindexstats). **Example** Example request: ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="YOUR_INDEX_HOST" curl -X GET "https://$INDEX_HOST/describe_index_stats" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` Example response: ```json curl expandable theme={null} { "namespaces": { "__default__": { "vectorCount": 705000 } }, "indexFullness": 0.01, "totalVectorCount": 705000, "dimension": 1536, "metric": "cosine", "vectorType": "dense", "memoryFullness": 0.01, "storageFullness": 0.01 } ``` In the response, `indexFullness` describes how full the index is, on a scale of 0 to 1. It's set to the greater of `memoryFullness` and `storageFullness`. To add or remove [shards](#shards), call [Configure an index](/reference/api/2025-10/control-plane/configure_index). This operation does not require downtime, but can take up to 30 minutes to complete. In the request body, set the following fields: | Field | Value | Notes | | :---------------------------------------------------------- | :---------------------------------- | :------------------------------------ | | **`spec.serverless.read_capacity.mode`** | `Dedicated` | | | **`spec.serverless.read_capacity.dedicated.scaling`** | `Manual` | | | **`spec.serverless.read_capacity.dedicated.manual.shards`** | Desired number of [shards](#shards) | Each shard provides 250 GB of storage | **Example** Example request: ```bash curl expandable theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="YOUR_INDEX_NAME" curl -X PATCH "https://api.pinecone.io/indexes/$INDEX_NAME" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "spec": { "serverless": { "read_capacity": { "mode": "Dedicated", "dedicated": { "scaling": "Manual", "manual": { "shards": 3 } } } } } }' ``` Example response: ```jsonc curl expandable theme={null} { "name": "example-dedicated-index", "vector_type": "dense", "metric": "cosine", "dimension": 1024, "status": { "ready": true, "state": "Ready" }, "host": "example-dedicated-index-1c6ab6aa.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 3, // <---- desired state "replicas": 1 } }, "status": { "state": "Scaling", "current_shards": 2, // <---- current state "current_replicas": 1 } } } }, "deletion_protection": "disabled", "tags": null, "embed": { "model": "llama-text-embed-v2", "field_map": { "text": "text" }, "dimension": 1024, "metric": "cosine", "write_parameters": { "dimension": 1024, "input_type": "passage", "truncate": "END" }, "read_parameters": { "dimension": 1024, "input_type": "query", "truncate": "END" }, "vector_type": "dense" } } ``` Configuration change limits: * You can make one configuration change every ten minutes, but you can batch multiple changes (node type, shards, and replicas) in a single request. * A new configuration change can only be initiated after the previous configuration change has completed. * Each configuration change can take up to 30 minutes to complete. * Read and write operations continue normally during configuration changes. To add or remove [replicas](#replicas), call [Configure an index](/reference/api/2025-10/control-plane/configure_index). This operation does not require downtime, but can take up to 30 minutes to complete. In the request body, set the following fields: | Field | Value | Notes | | :------------------------------------------------------------ | :-------------------------------------- | :---------------------------------------- | | **`spec.serverless.read_capacity.mode`** | `Dedicated` | | | **`spec.serverless.read_capacity.dedicated.scaling`** | `Manual` | | | **`spec.serverless.read_capacity.dedicated.manual.replicas`** | Desired number of [replicas](#replicas) | Add replicas to increase query throughput | **Example** Example request: ```bash curl expandable theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="YOUR_INDEX_NAME" curl -X PATCH "https://api.pinecone.io/indexes/$INDEX_NAME" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "spec": { "serverless": { "read_capacity": { "mode": "Dedicated", "dedicated": { "scaling": "Manual", "manual": { "replicas": 2 } } } } } }' ``` Example response: ```jsonc curl expandable theme={null} { "name": "example-dedicated-index", "vector_type": "dense", "metric": "cosine", "dimension": 1024, "status": { "ready": true, "state": "Ready" }, "host": "example-dedicated-index-1c6ab6aa.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 1, "replicas": 2 // <---- desired state } }, "status": { "state": "Scaling", "current_shards": 1, "current_replicas": 1 // <---- current state } } } }, "deletion_protection": "disabled", "tags": null, "embed": { "model": "llama-text-embed-v2", "field_map": { "text": "text" }, "dimension": 1024, "metric": "cosine", "write_parameters": { "dimension": 1024, "input_type": "passage", "truncate": "END" }, "read_parameters": { "dimension": 1024, "input_type": "query", "truncate": "END" }, "vector_type": "dense" } } ``` Configuration change limits: * You can make one configuration change every ten minutes, but you can batch multiple changes (node type, shards, and replicas) in a single request. * A new configuration change can only be initiated after the previous configuration change has completed. * Each configuration change can take up to 30 minutes to complete. * Read and write operations continue normally during configuration changes. You can change node types in either direction (`b1` → `t1` or `t1` → `b1`). This operation does not require downtime, but can take up to 30 minutes to complete. The most predictable way to increase throughput is by increasing [replicas](#replicas). `t1` nodes [cache more data in memory](#node-types) than `b1` nodes. Because of this, switching from `b1` to `t1` may require more shards. If your new configuration doesn't have enough shards, the configuration change will fail with an error telling you how many shards are required. Update the request and retry. In the meantime, your index will continue to function normally in its original configuration. To change node types, call [Configure an index](/reference/api/2025-10/control-plane/configure_index). In the request body, set the following fields: | Field | Value | Notes | | :------------------------------------------------------ | :----------- | :---------------------------- | | **`spec.serverless.read_capacity.mode`** | `Dedicated` | | | **`spec.serverless.read_capacity.dedicated.node_type`** | `b1` or `t1` | See [node types](#node-types) | **Example** Example request to change from `b1` to `t1`: ```bash curl expandable theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="YOUR_INDEX_NAME" curl -X PATCH "https://api.pinecone.io/indexes/$INDEX_NAME" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "spec": { "serverless": { "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "t1" } } } } }' ``` Example response: ```json curl expandable theme={null} { "name": "example-dedicated-index", "vector_type": "dense", "metric": "cosine", "dimension": 1024, "status": { "ready": true, "state": "Ready" }, "host": "example-dedicated-index-1c6ab6aa.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "t1", "scaling": "Manual", "manual": { "shards": 1, "replicas": 1 } }, "status": { "state": "Scaling", "current_shards": 1, "current_replicas": 1 } } } }, "deletion_protection": "disabled", "tags": null, "embed": { "model": "llama-text-embed-v2", "field_map": { "text": "text" }, "dimension": 1024, "metric": "cosine", "write_parameters": { "dimension": 1024, "input_type": "passage", "truncate": "END" }, "read_parameters": { "dimension": 1024, "input_type": "query", "truncate": "END" }, "vector_type": "dense" } } ``` Configuration change limits: * You can make one configuration change every ten minutes, but you can batch multiple changes (node type, shards, and replicas) in a single request. * A new configuration change can only be initiated after the previous configuration change has completed. * Each configuration change can take up to 30 minutes to complete. * Read and write operations continue normally during configuration changes. To pause an index, [set the number of replicas](#add-or-remove-replicas) to 0. This operation can take up to 30 minutes to complete. While an index is paused, you cannot write to it or read from it. For a paused index, you're billed for storage, but not for node costs, reads, or writes. After making a configuration change to a dedicated read nodes index (changing shards, replicas, or node type), check the status of the change by calling [Describe an index](/reference/api/2025-10/control-plane/describe_index). **Example** Example request: ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="YOUR_INDEX_NAME" curl -X GET "https://api.pinecone.io/indexes/$INDEX_NAME" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` Example response (index scaling from one to two replicas): ```jsonc curl expandable theme={null} { "name": "example-dedicated-index", "vector_type": "dense", "metric": "cosine", "dimension": 1536, "status": { "ready": true, "state": "Ready" }, "host": "example-dedicated-index-1c6ab6aa.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 1, "replicas": 2 // <---- desired state } }, "status": { "state": "Scaling", "current_shards": 1, "current_replicas": 1 // <---- current state } } } }, "deletion_protection": "enabled", "tags": { "tag0": "value0" } } ``` The response includes two status fields: | Field | Description | | :----------------------------------------------- | :------------------------------------------------------------------------- | | **`status.state`** | Overall index status (for example, `Initializing`, `Ready`, `Terminating`) | | **`spec.serverless.read_capacity.status.state`** | Read capacity status (`Migrating`, `Scaling`, `Ready`, `Error`) | When changing node types, shards, or replicas, monitor the read capacity status (`spec.serverless.read_capacity.status.state`). Possible values: | State | Description | | :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`Ready`** | The change is complete and the index is ready to serve queries at full capacity. | | **`Scaling`** | A change to the number of shards or replicas is in progress. | | **`Migrating`** | A change to the node type or read capacity mode is in progress. | | **`Error`** | The operation failed. For migrations to dedicated, this typically means you didn't allocate enough shards for your index size. Check `error_message` for details, and retry with more shards. | During changes to shards, replicas, and node type, the index-level status (`status.state`) remains `Ready`. This is because the index can handle reads and writes while its dedicated read capacity scales. Configuration change limits: * You can make one configuration change every ten minutes, but you can batch multiple changes (node type, shards, and replicas) in a single request. * A new configuration change can only be initiated after the previous configuration change has completed. * Each configuration change can take up to 30 minutes to complete. * Read and write operations continue normally during configuration changes. You cannot directly convert a dedicated read nodes index to on-demand with the API. Instead, you can migrate your data by [backing up your index](/guides/manage-data/back-up-an-index) and then [restoring it into a new serverless index](/guides/manage-data/restore-an-index) without dedicated read nodes enabled. 1. [Create a backup](/guides/manage-data/back-up-an-index) of your dedicated read nodes index. 2. [Create a new index from the backup](/guides/manage-data/restore-an-index), without specifying dedicated read node configuration. 3. Verify the new on-demand index and update your application to use it. 4. Delete the old dedicated read nodes index. If you have concerns or need assistance, [contact support](https://app.pinecone.io/organizations/-/settings/support/ticket). ## Limits The following limits apply to dedicated read nodes: Dedicated read nodes indexes are not subject to [read-operation rate limits](/reference/api/database-limits#rate-limits), like on-demand indexes are. However, if your query rate exceeds the compute capacity of your index, you may observe decreased query throughput. In such cases, consider [adding replicas](#add-or-remove-replicas) to increase compute resources, or use [query-time search parameters](#query-time-search-parameters) to reduce per-query compute and increase throughput without adding replicas. On dedicated read nodes indexes, write operations (upsert, update, delete) have the same [rate limits](/reference/api/database-limits#rate-limits) as on-demand indexes. Writes that would cause your index to exceed its storage capacity are blocked. In such cases, consider [adding shards](#add-or-remove-shards) to increase available storage. To determine how close to the write limit you are, [check index fullness](#monitor-index-fullness). Currently, dedicated read nodes indexes only support a single namespace. However, multi-namespace support is coming soon. For early access, [contact support](https://app.pinecone.io/organizations/-/settings/support/ticket). **Shards** The minimum number of [shards](#shards) per index is 1. **Replicas** The minimum number of [replicas](#replicas) per index is 0, which [pauses the index](#pause-an-index). **Nodes** The maximum number of [nodes](#node-types) per project is 20. This is a **project** limit, not an index limit. To calculate your total node count, multiply `shards × replicas` for each of your project's indexes, and then sum the results. This total must not exceed 20. For example, if you have two indexes that each have two shards and three replicas, your total node count is `(2 × 3) + (2 × 3) = 12` nodes. To increase your project's node limit, [contact support](https://app.pinecone.io/organizations/-/settings/support/ticket). Configuration change limits: * You can make one configuration change every ten minutes, but you can batch multiple changes (node type, shards, and replicas) in a single request. * A new configuration change can only be initiated after the previous configuration change has completed. * Each configuration change can take up to 30 minutes to complete. * Read and write operations continue normally during configuration changes. `memoryFullness` is an approximation and doesn't yet account for metadata. For more information, see [Index fullness](#index-fullness). To migrate an index from dedicated to on-demand, [contact support](https://app.pinecone.io/organizations/-/settings/support/ticket). This cannot be done with the API. ## Cost For the latest pricing information, see the [Pinecone pricing page](https://www.pinecone.io/pricing/). The cost of an index has three components: read costs, write costs, and storage costs. On-demand and dedicated read nodes share infrastructure for writes and storage, so these costs are the same. However, dedicated read nodes provision dedicated hardware for read operations (query, fetch, list), which changes how read costs are calculated. | Cost component | On-demand | Dedicated read nodes | | :---------------- | :------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- | | **Read costs** | [Usage-based](/guides/manage-cost/understanding-cost#read-units): 1 RU per 1 GB namespace size per query | Fixed hourly rate: Based on [node type](#node-types), [shards](#shards), and [replicas](#replicas) | | **Write costs** | [Usage-based](/guides/manage-cost/understanding-cost#write-units) | [Usage-based](/guides/manage-cost/understanding-cost#write-units) (same as on-demand) | | **Storage costs** | [Usage-based](/guides/manage-cost/understanding-cost#storage) | [Usage-based](/guides/manage-cost/understanding-cost#storage) (same as on-demand) | If you use a hosted model for search or reranking, there are additional [inference costs](https://www.pinecone.io/pricing). To calculate the total cost of a dedicated read nodes index, use this formula: ``` (Node rate × shards × replicas) + storage costs + write costs ``` | Term | Description | | :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- | | **Node rate** | Monthly rate for the [node type](#node-types) (`b1` or `t1`), which varies by cloud region. See [Pinecone pricing](https://www.pinecone.io/pricing/). | | **Shards** | Number of [shards](#shards) allocated | | **Replicas** | Number of [replicas](#replicas) allocated | | **Storage costs** | [Usage-based](/guides/manage-cost/understanding-cost#storage), same as on-demand | | **Write costs** | [Usage-based](/guides/manage-cost/understanding-cost#write-units), same as on-demand | For help estimating costs, use the [Pinecone pricing calculator](https://www.pinecone.io/pricing/estimate/) or [contact us](https://www.pinecone.io/contact/). **Example:** If the rate for `b1` nodes on `aws-us-east-1` is \$336.42/month (\$0.46/hour), an index with two shards and two replicas would cost: ``` 336.42 × 2 × 2 = $1,345.68/month, plus storage and write costs ``` # Implement multitenancy Source: https://docs.pinecone.io/guides/index-data/implement-multitenancy Implement multitenancy in Pinecone with one namespace per tenant on a serverless index to isolate customer data for SaaS RAG or semantic search apps. [Multitenancy](https://en.wikipedia.org/wiki/Multitenancy) is a software architecture where a single instance of a system serves multiple customers, or tenants, while ensuring data isolation between them for privacy and security. This page shows you how to implement multitenancy in Pinecone using a **serverless index with one namespace per tenant**. For design guidance on choosing between namespaces, metadata filtering, and other approaches, see [Design for multi-tenancy](/guides/index-data/data-modeling#design-for-multi-tenancy). [Namespaces per serverless index](/reference/api/database-limits#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](https://app.pinecone.io/organizations/-/settings/support/ticket). ## How it works In Pinecone, an [index](/guides/index-data/indexing-overview) is the highest-level organizational unit of data, where you define the dimension of vectors to be stored in the index and the measure of similarity to be used when querying the index. Within an index, records are stored in [namespaces](/guides/index-data/indexing-overview#namespaces), and all [upserts](/guides/index-data/upsert-data), [queries](/guides/search/search-overview), and other data read and write operations always target one namespace. This structure makes it easy to implement multitenancy. For example, for an AI-powered SaaS application where you need to isolate the data of each customer, you would assign each customer to a namespace and target their writes and queries to that namespace (diagram above). In cases where you have different workload patterns (e.g., RAG and semantic search), you would use a different index for each workload, with one namespace per customer in each index: * **Tenant isolation:** In the [serverless architecture](/guides/get-started/database-architecture), each namespace is stored separately, so using namespaces provides physical isolation of data between tenants/customers. This reduces the risk of application bugs that could query the wrong tenant's data. * **No noisy neighbors:** Reads and writes always target a single namespace, so the behavior of one tenant/customer does not affect other tenants/customers. * **No maintenance effort:** Serverless indexes scale automatically based on usage; you don't configure or manage any compute or storage resources. * **Cost efficiency:** Query cost is based on namespace size (1 RU per 1 GB). With 100 tenants of 1 GB each, querying one tenant's namespace costs 1 RU. Using metadata filtering in a single 100 GB namespace would cost 100 RUs for the same query, because it scans all data regardless of filters. * **Simple tenant offboarding:** To offboard a tenant/customer, you just [delete the relevant namespace](/guides/manage-data/delete-data#delete-all-records-from-a-namespace). This is a lightweight and almost instant operation. ## 1. Create a serverless index Based on a [breakthrough architecture](/guides/get-started/database-architecture), serverless indexes scale automatically based on usage, and you pay only for the amount of data stored and operations performed. Combined with the isolation of tenant data using namespaces (next step), serverless indexes are ideal for multitenant use cases. To [create a serverless index](/guides/index-data/create-an-index#create-a-serverless-index), use the `spec` parameter to define the cloud and region where the index should be deployed. For Python, you also need to import the `ServerlessSpec` class. ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="multitenant-app", dimension=8, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ) ) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createIndex({ name: 'multitenant-app', dimension: 8, metric: 'cosine', spec: { serverless: { cloud: 'aws', region: 'us-east-1' } } }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; public class CreateServerlessIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.createServerlessIndex("multitenant-app", "cosine", 8, "aws", "us-east-1"); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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) } // Serverless index indexName := "multi-tenant-app" vectorType := "dense" dimension := int32(8) metric := pinecone.Cosine deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: indexName, VectorType: &vectorType, Dimension: &dimension, Metric: &metric, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: &deletionProtection, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", err) } else { fmt.Printf("Successfully created serverless index: %v", idx.Name) } } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "multitenant-app", "dimension": 8, "metric": "cosine", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } } }' ``` ## 2. Isolate tenant data In a multitenant solution, you need to isolate data between tenants. To achieve this in Pinecone, use one namespace per tenant. In the [serverless architecture](/guides/get-started/database-architecture), each namespace is stored separately, so this approach ensures physical isolation of each tenant's data. To [create a namespace for a tenant](/guides/index-data/indexing-overview#namespaces#creating-a-namespace), specify the `namespace` parameter when first [upserting](/guides/index-data/upsert-data) the tenant's records. For example, the following code upserts records for `tenant1` and `tenant2` into the `multitenant-app` index: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index("multitenant-app") index.upsert( vectors=[ {"id": "A", "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1]}, {"id": "B", "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]}, {"id": "C", "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]}, {"id": "D", "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]} ], namespace="tenant1" ) index.upsert( vectors=[ {"id": "E", "values": [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5]}, {"id": "F", "values": [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6]}, {"id": "G", "values": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7]}, {"id": "H", "values": [0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8]} ], namespace="tenant2" ) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }); const index = pc.index("multitenant-app"); await index.namespace("tenant1").upsert([ { "id": "A", "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1] }, { "id": "B", "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2] }, { "id": "C", "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3] }, { "id": "D", "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4] } ]); await index.namespace("tenant2").upsert([ { "id": "E", "values": [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5] }, { "id": "F", "values": [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6] }, { "id": "G", "values": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7] }, { "id": "H", "values": [0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8] } ]); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.clients.Pinecone; import java.util.Arrays; import java.util.List; public class UpsertExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); String indexName = "multitenant-app"; Index index = pc.getIndexConnection(indexName); List values1 = Arrays.asList(0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f); List values2 = Arrays.asList(0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f); List values3 = Arrays.asList(0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f); List values4 = Arrays.asList(0.4f, 0.4f, 0.4f, 0.4f, 0.4f, 0.4f, 0.4f, 0.4f); List values5 = Arrays.asList(0.5f, 0.5f, 0.5f, 0.5f, 0.5f, 0.5f, 0.5f, 0.5f); List values6 = Arrays.asList(0.6f, 0.6f, 0.6f, 0.6f, 0.6f, 0.6f, 0.6f, 0.6f); List values7 = Arrays.asList(0.7f, 0.7f, 0.7f, 0.7f, 0.7f, 0.7f, 0.7f, 0.7f); List values8 = Arrays.asList(0.8f, 0.8f, 0.8f, 0.8f, 0.8f, 0.8f, 0.8f, 0.8f); index.upsert("A", values1, "tenant1"); index.upsert("B", values2, "tenant1"); index.upsert("C", values3, "tenant1"); index.upsert("D", values4, "tenant1"); index.upsert("E", values5, "tenant2"); index.upsert("F", values6, "tenant2"); index.upsert("G", values7, "tenant2"); index.upsert("H", values8, "tenant2"); } } ``` ```go Go theme={null} // Add to the main function: idx, err := pc.DescribeIndex(ctx, indexName) if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err) } idxConnection1, err := pc.Index(pinecone.NewIndexConnParams{Host: idx.Host, Namespace: "tenant1"}) if err != nil { log.Fatalf("Failed to create IndexConnection1 for Host %v: %v", idx.Host, err) } // This reuses the gRPC connection of idxConnection1 while targeting a different namespace idxConnection2 := idxConnection1.WithNamespace("tenant2") vectors1 := []*pinecone.Vector{ { Id: "A", Values: []float32{0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1}, }, { Id: "B", Values: []float32{0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2}, }, { Id: "C", Values: []float32{0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3}, }, { Id: "D", Values: []float32{0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4}, }, } vectors2 := []*pinecone.Vector{ { Id: "E", Values: []float32{0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5}, }, { Id: "F", Values: []float32{0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6}, }, { Id: "G", Values: []float32{0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7}, }, { Id: "H", Values: []float32{0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8}, }, } count1, err := idxConnection1.UpsertVectors(ctx, vectors1) if err != nil { log.Fatalf("Failed to upsert vectors: %v", err) } else { fmt.Printf("Successfully upserted %d vector(s)!\n", count1) } count2, err := idxConnection2.UpsertVectors(ctx, vectors2) if err != nil { log.Fatalf("Failed to upsert vectors: %v", err) } else { fmt.Printf("Successfully upserted %d vector(s)!\n", count2) } ``` ```bash curl theme={null} # The `POST` requests below uses the unique endpoint for an index. # See https://docs.pinecone.io/guides/manage-data/target-an-index for details. PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/vectors/upsert" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "vectors": [ { "id": "A", "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1] }, { "id": "B", "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2] }, { "id": "C", "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3] }, { "id": "D", "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4] } ], "namespace": "tenant1" }' curl "https://$INDEX_HOST/vectors/upsert" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "vectors": [ { "id": "E", "values": [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5] }, { "id": "F", "values": [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6] }, { "id": "G", "values": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7] }, { "id": "H", "values": [0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8] } ], "namespace": "tenant2" }' ``` When upserting additional records for a tenant, or when [updating](/guides/manage-data/update-data) or [deleting](/guides/manage-data/delete-data) records for a tenant, specify the tenant's `namespace`. For example, the following code updates the dense vector value of record `A` in `tenant1`: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index("multitenant-app") index.update(id="A", values=[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8], namespace="tenant1") ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }); const index = pc.index("multitenant-app"); await index.namespace('tenant1').update({ id: 'A', values: [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8] }); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.clients.Pinecone; import io.pinecone.proto.UpdateResponse; import java.util.Arrays; import java.util.List; public class UpdateExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); Index index = pc.getIndexConnection("multitenant-app"); List values = Arrays.asList(0.1f, 0.2f, 0.3f, 0.4f, 0.5f, 0.6f, 0.7f, 0.8f); UpdateResponse updateResponse = index.update("A", values, null, "tenant1", null, null); System.out.println(updateResponse); } } ``` ```go Go theme={null} // Add to the main function: idxConn1.UpdateVector(ctx, &pinecone.UpdateVectorRequest{ Id: "A", Values: []float32{0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8}, }) if err != nil { log.Fatalf("Failed to update vector with ID %v: %v", id, err) } ``` ```bash curl theme={null} # The `POST` request below uses the unique endpoint for an index. # See https://docs.pinecone.io/guides/manage-data/target-an-index for details. PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/vectors/update" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "id": "A", "values": [01., 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8], "namespace": "tenant1" }' ``` ## 3. Query tenant data In a multitenant solution, you need to ensure that the queries of one tenant do not affect the experience of other tenants/customers. To achieve this in Pinecone, target each tenant's [queries](/guides/search/search-overview) at the namespace for the tenant. For example, the following code queries only `tenant2` for the 3 vectors that are most similar to an example query vector: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index("multitenant-app") query_results = index.query( namespace="tenant2", vector=[0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7], top_k=3, include_values=True ) print(query_results) # Returns: # {'matches': [{'id': 'F', # 'score': 1.00000012, # 'values': [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6]}, # {'id': 'G', # 'score': 1.0, # 'values': [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7]}, # {'id': 'E', # 'score': 1.0, # 'values': [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5]}], # 'namespace': 'tenant2', # 'usage': {'read_units': 6}} ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }); const index = pc.index("multitenant-app"); const queryResponse = await index.namespace("tenant2").query({ topK: 3, vector: [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7], includeValues: true }); console.log(queryResponse); // Returns: { "matches": [ { "id": "F", "score": 1.00000012, "values": [ 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6 ] }, { "id": "E", "score": 1, "values": [ 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5 ] }, { "id": "G", "score": 1, "values": [ 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7 ] } ], "namespace": "tenant2", "usage": { "readUnits": 6 } } ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.clients.Pinecone; import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices; import java.util.Arrays; import java.util.List; public class QueryExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); String indexName = "multitenant-app"; Index index = pc.getIndexConnection(indexName); List queryVector = Arrays.asList(0.7f, 0.7f, 0.7f, 0.7f, 0.7f, 0.7f, 0.7f, 0.7f); QueryResponseWithUnsignedIndices queryResponse = index.query(3, queryVector2, null, null, null, "tenant2", null, true, false); System.out.println(queryResponse); } } // Results: // class QueryResponseWithUnsignedIndices { // matches: [ScoredVectorWithUnsignedIndices { // score: 1.00000012 // id: F // values: [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6] // metadata: // sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices { // indicesWithUnsigned32Int: [] // values: [] // } // }, ScoredVectorWithUnsignedIndices { // score: 1 // id: E // values: [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5] // metadata: // sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices { // indicesWithUnsigned32Int: [] // values: [] // } // }, ScoredVectorWithUnsignedIndices { // score: 0.07999992 // id: G // values: [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7] // metadata: // sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices { // indicesWithUnsigned32Int: [] // values: [] // } // }] // namespace: tenant2 // usage: read_units: 6 // } ``` ```go Go theme={null} // Add to the main function: queryVector := []float32{0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7} res, err := idxConnection2.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{ Vector: queryVector, TopK: 3, IncludeValues: true, }) if err != nil { log.Fatalf("Error encountered when querying by vector: %v", err) } else { fmt.Printf(prettifyStruct(res)) } // Returns: // { // "matches": [ // { // "vector": { // "id": "F", // "values": [ // 0.6, // 0.6, // 0.6, // 0.6, // 0.6, // 0.6, // 0.6, // 0.6 // ] // }, // "score": 1.0000001 // }, // { // "vector": { // "id": "G", // "values": [ // 0.7, // 0.7, // 0.7, // 0.7, // 0.7, // 0.7, // 0.7, // 0.7 // ] // }, // "score": 1 // }, // { // "vector": { // "id": "H", // "values": [ // 0.8, // 0.8, // 0.8, // 0.8, // 0.8, // 0.8, // 0.8, // 0.8 // ] // }, // "score": 1 // } // ], // "usage": { // "read_units": 6 // } // } ``` ```shell curl theme={null} # The `POST` requests below uses the unique endpoint for an index. # See https://docs.pinecone.io/guides/manage-data/target-an-index for details. PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/query" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "namespace": "tenant2", "vector": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7], "topK": 3, "includeValues": true }' # # Output: # { # "matches": [ # { # "id": "F", # "score": 1.00000012, # "values": [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6] # }, # { # "id": "E", # "score": 1, # "values": [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5] # }, # { # "id": "G", # "score": 1, # "values": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7] # } # ], # "namespace": "tenant2", # "usage": {"read_units": 6} # } ``` ## 4. Offboard a tenant In a multitenant solution, you also need it to be quick and easy to offboard a tenant and delete all of its records. To achieve this in Pinecone, you just [delete the namespace](/guides/manage-data/delete-data#delete-an-entire-namespace) for the specific tenant. For example, the following code deletes the namespace and all records for `tenant1`: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index("multitenant-app") index.delete(delete_all=True, namespace='tenant1') ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }); const index = pc.index("multitenant-app"); await index.namespace('tenant1').deleteAll(); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.clients.Pinecone; public class DeleteVectorsExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); Index index = pc.getIndexConnection("multitenant-app"); index.deleteAll("tenant1"); } } ``` ```go Go theme={null} // Add to the main function: idxConnection1.DeleteAllVectorsInNamespace(ctx) if err != nil { log.Fatalf("Failed to delete vectors in namespace \"%v\": %v", idxConnection2.Namespace, err) } ``` ```bash curl theme={null} # The `POST` request below uses the unique endpoint for an index. # See https://docs.pinecone.io/guides/manage-data/target-an-index for details. PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/vectors/delete" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "deleteAll": true, "namespace": "tenant1" } ' ``` ## Alternative: Metadata filtering When tenant isolation is not a strict requirement, or when you need to query across multiple tenants simultaneously, you can store all records in a single namespace and use metadata fields to assign records to tenants/customers. At query time, you can then [filter by metadata](/guides/index-data/indexing-overview#metadata). This approach has significant performance and cost tradeoffs compared to using namespaces: * Higher query costs: Queries scan the entire namespace regardless of filters, so you pay for scanning all tenants' data even though results are filtered to one tenant. * Slower performance: Large namespaces increase query latency, and large filters add network overhead on the request side. * Filter size limits: Each `$in` or `$nin` operator is limited to 10,000 values. Exceeding this limit will cause requests to fail. See [Metadata filter limits](/reference/api/database-limits#metadata-filter-limits). Anti-pattern: Avoid filtering by large lists of individual user IDs. Instead, use access control groups (organization, project, role), namespaces, or post-filter client-side (for semantic search). For detailed guidance on choosing between namespaces and metadata filtering, see [Design for multi-tenancy](/guides/index-data/data-modeling#design-for-multi-tenancy). For more background on this approach, see [Multitenancy in Vector Databases](https://www.pinecone.io/learn/series/vector-databases-in-production-for-busy-engineers/vector-database-multi-tenancy/). # Import records Source: https://docs.pinecone.io/guides/index-data/import-data Import large datasets efficiently from Amazon S3, Google Cloud Storage, or Azure Blob Storage into Pinecone serverless indexes using object storage. Importing from object storage is the most efficient and cost-effective way to load large numbers of records into an index. To run through this guide in your browser, see the [Bulk import colab notebook](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/pinecone-import.ipynb). This feature is available on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). ## Before you import Before you can import records, ensure you have a serverless index, a storage integration, and data formatted in a Parquet file and uploaded to an Amazon S3 bucket, Google Cloud Storage bucket, or Azure Blob Storage container. ### Create an index [Create a serverless index](/guides/index-data/create-an-index) for your data. Be sure to create your index on a cloud that supports importing from the object storage you want to use: | | …to an **AWS** index | …to a **GCP** index | …to an **Azure** index | | ------------------------------------- | :------------------: | :-----------------: | :--------------------: | | Import from **AWS S3**… | ✅ | ❌ | ❌ | | Import from **Google Cloud Storage**… | ✅ | ✅ | ✅ | | Import from **Azure Blob Storage**… | ✅ | ✅ | ✅ | ### Add a storage integration To import records from a public data source, a storage integration is not required. However, to import records from a secure data source, you must create an integration to allow Pinecone access to data in your object storage. See the following guides: * [Integrate with Amazon S3](/guides/operations/integrations/integrate-with-amazon-s3) * [Integrate with Google Cloud Storage](/guides/operations/integrations/integrate-with-google-cloud-storage) * [Integrate with Azure Blob Storage](/guides/operations/integrations/integrate-with-azure-blob-storage) ### Prepare your data 1. In your Amazon S3 bucket, Google Cloud Storage bucket, or Azure Blob Storage container, create an import directory containing a subdirectory for each namespace you want to import into. The namespaces must not yet exist in your index. For example, to import data into the namespaces `example_namespace1` and `example_namespace2`, your directory structure would look like this: ``` / --// ----/example_namespace1/ ----/example_namespace2/ ``` To import into the default namespace, use a subdirectory called `__default__`. The default namespace must be empty. 2. For each namespace, create one or more Parquet files defining the records to import. Parquet files must contain specific columns, depending on the index type: To import into a namespace in an [index of dense vectors](/guides/index-data/indexing-overview#indexes-with-dense-vectors), the Parquet file must contain the following columns: | Column name | Parquet type | Description | | ----------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `id` | `STRING` | Required. The unique [identifier for each record](/guides/get-started/concepts#record-id). | | `values` | `LIST` | Required. A list of floating-point values that make up the [dense vector embedding](/guides/get-started/concepts#dense-vector). | | `metadata` | `STRING` | Optional. Additional [metadata](/guides/get-started/concepts#metadata) for each record. To omit from specific rows, use `NULL`. | Additional columns in the Parquet file are silently ignored during import; only `id`, `values`, and `metadata` are processed. For example: ```parquet theme={null} id | values | metadata -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 1 | [ 3.82 2.48 -4.15 ... ] | {"year": 1984, "month": 6, "source": "source1", "title": "Example1", "text": "When ..."} 2 | [ 1.82 3.48 -2.15 ... ] | {"year": 1990, "month": 4, "source": "source2", "title": "Example2", "text": "Who ..."} ``` To import into a namespace in an [index of sparse vectors](/guides/index-data/indexing-overview#indexes-with-sparse-vectors), the Parquet file must contain the following columns: | Column name | Parquet type | Description | | --------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `STRING` | Required. The unique [identifier for each record](/guides/get-started/concepts#record-id). | | `sparse_values` | `STRUCT, values: LIST>` | Required. A list of floating-point values (sparse values) and a list of integer values (sparse indices) that make up the [sparse vector embedding](/guides/get-started/concepts#sparse-vector). | | `metadata` | `STRING` | Optional. Additional [metadata](/guides/get-started/concepts#metadata) for each record. To omit from specific rows, use `NULL`. | Additional columns in the Parquet file are silently ignored during import; only `id`, `sparse_values`, and `metadata` are processed. For example: ```parquet theme={null} id | sparse_values | metadata -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 1 | {"indices": [ 822745112 1009084850 1221765879 ... ], "values": [1.7958984 0.41577148 2.828125 ...]} | {"year": 1984, "month": 6, "source": "source1", "title": "Example1", "text": "When ..."} 2 | {"indices": [ 504939989 1293001993 3201939490 ... ], "values": [1.4383747 0.72849722 1.384775 ...]} | {"year": 1990, "month": 4, "source": "source2", "title": "Example2", "text": "Who ..."} ``` To import into a namespace in an [index with both dense and sparse vectors](/guides/search/hybrid-search#use-a-single-index-for-dense-and-sparse-vectors), the Parquet file must contain the following columns: | Column name | Parquet type | Description | | --------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `STRING` | Required. The unique [identifier for each record](/guides/get-started/concepts#record-id). | | `values` | `LIST` | Required. A list of floating-point values that make up the [dense vector embedding](/guides/get-started/concepts#dense-vector). | | `sparse_values` | `STRUCT, values: LIST>` | Optional. A list of floating-point values that make up the [sparse vector embedding](/guides/get-started/concepts#sparse-vector). To omit from specific rows, use `NULL`. | | `metadata` | `STRING` | Optional. Additional [metadata](/guides/get-started/concepts#metadata) for each record. To omit from specific rows, use `NULL`. | Additional columns in the Parquet file are silently ignored during import; only `id`, `values`, `sparse_values`, and `metadata` are processed. For example: ```parquet theme={null} id | values | sparse_values | metadata -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 1 | [ 3.82 2.48 -4.15 ... ] | {"indices": [1082468256, 1009084850, 1221765879, ...], "values": [2.0, 3.0, 4.0, ...]} | {"year": 1984, "month": 6, "source": "source1", "title": "Example1", "text": "When ..."} 2 | [ 1.82 3.48 -2.15 ... ] | {"indices": [2225824123, 1293001993, 3201939490, ...], "values": [5.0, 2.0, 3.0, ...]} | {"year": 1990, "month": 4, "source": "source2", "title": "Example2", "text": "Who ..."} ``` 3. Upload the Parquet files into the relevant subdirectory. For example, if you have subdirectories for the namespaces `example_namespace1` and `example_namespace2` and upload 4 Parquet files into each, your directory structure would look as follows after the upload: ``` / --// ----/example_namespace1/ ------0.parquet ------1.parquet ------2.parquet ------3.parquet ----/example_namespace2/ ------4.parquet ------5.parquet ------6.parquet ------7.parquet ``` ## Import records into an index Review [import limits](#import-limits) before starting an import. This guide covers importing Parquet files into indexes **without** a schema definition. Indexes with document schemas import [JSONL files](/guides/search/full-text-search#bulk-import) instead. Semantic-text (auto-embedded) fields are not yet supported in document schemas. Use the [`start_import`](/reference/api/latest/data-plane/start_import) operation to start an asynchronous import of vectors from object storage into an index. * For `uri`, specify the URI of the bucket and import directory containing the namespaces and Parquet files you want to import. For example: * Amazon S3: `s3://BUCKET_NAME/IMPORT_DIR` * Google Cloud Storage: `gs://BUCKET_NAME/IMPORT_DIR` * Azure Blob Storage: `https://STORAGE_ACCOUNT.blob.core.windows.net/CONTAINER_NAME/IMPORT_DIR` * For `integration_id`, specify the Integration ID of the Amazon S3, Google Cloud Storage, or Azure Blob Storage integration you created. The ID is found on the [Storage integrations](https://app.pinecone.io/organizations/-/projects/-/storage) page of the Pinecone console. An Integration ID is not needed to import from a public bucket. * For `error_mode`, use `continue` or `abort`. * With `abort`, the operation stops if any records fail to import. * With `continue`, the operation continues on error, but there is not any notification about which records, if any, failed to import. To see how many records were successfully imported, use the [describe an import](#describe-an-import) operation. ```python Python theme={null} from pinecone import Pinecone, ImportErrorMode pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") root = "s3://example_bucket/import" index.start_import( uri=root, integration_id="a12b3d4c-47d2-492c-a97a-dd98c8dbefde", # Optional for public buckets error_mode=ImportErrorMode.CONTINUE # or ImportErrorMode.ABORT ) ``` ```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/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const storageURI = 's3://example_bucket/import'; const errorMode = 'continue'; // or 'abort' const integrationID = 'a12b3d4c-47d2-492c-a97a-dd98c8dbefde'; // Optional for public buckets await index.startImport(storageURI, errorMode, integrationID); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import io.pinecone.clients.AsyncIndex; import org.openapitools.db_data.client.ApiException; import org.openapitools.db_data.client.model.ImportErrorMode; import org.openapitools.db_data.client.model.StartImportResponse; public class StartImport { public static void main(String[] args) throws ApiException { // Initialize a Pinecone client with your API key Pinecone pinecone = new Pinecone.Builder("YOUR_API_KEY").build(); // Get async imports connection object AsyncIndex asyncIndex = pinecone.getAsyncIndexConnection("docs-example"); // s3 uri String uri = "s3://example_bucket/import"; // Integration ID (optional for public buckets) String integrationId = "a12b3d4c-47d2-492c-a97a-dd98c8dbefde"; // Start an import StartImportResponse response = asyncIndex.startImport(uri, integrationId, ImportErrorMode.OnErrorEnum.CONTINUE); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } uri := "s3://example_bucket/import" errorMode := "continue" // or "abort" importRes, err := idxConnection.StartImport(ctx, uri, nil, (*pinecone.ImportErrorMode)(&errorMode)) if err != nil { log.Fatalf("Failed to start import: %v", err) } fmt.Printf("Import started with ID: %s", importRes.Id) } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/bulk/imports" \ -H 'Api-Key: $YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -H 'X-Pinecone-Api-Version: 2025-10' \ -d '{ "integrationId": "a12b3d4c-47d2-492c-a97a-dd98c8dbefde", "uri": "s3://example_bucket/import", "errorMode": { "onError": "continue" } }' ``` The response contains an `id` that you can use to [check the status of the import](#list-imports): ```json Response theme={null} { "id": "101" } ``` Once all the data is loaded, the [index builder](/guides/get-started/database-architecture#index-builder) indexes the records, which usually takes at least 10 minutes. During this indexing process, the expected job status is `InProgress`, but `100.0` percent complete. Once all the imported records are indexed and fully available for querying, the import operation is set to `Completed`. If you cancel the import before it finishes, the status changes to `Cancelled`. You can start a new import using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes). Find the index you want to import into, and click the **ellipsis (...) menu > Import data**. ## Track import progress The amount of time required for an import depends on various factors, including: * The number of records to import * The number of namespaces to import, and the the number of records in each * The total size (in bytes) of the import To track an import's progress, check its status bar in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/import) or use the [`describe_import`](/reference/api/latest/data-plane/describe_import) operation with the import ID: ```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/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.describe_import(id="101") ``` ```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/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const results = await index.describeImport(id='101'); console.log(results); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import io.pinecone.clients.AsyncIndex; import org.openapitools.db_data.client.ApiException; import org.openapitools.db_data.client.model.ImportModel; public class DescribeImport { public static void main(String[] args) throws ApiException { // Initialize a Pinecone client with your API key Pinecone pinecone = new Pinecone.Builder("YOUR_API_KEY").build(); // Get async imports connection object AsyncIndex asyncIndex = pinecone.getAsyncIndexConnection("docs-example"); // Describe import ImportModel importDetails = asyncIndex.describeImport("101"); System.out.println(importDetails); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } importID := "101" importDesc, err := idxConnection.DescribeImport(ctx, importID) if err != nil { log.Fatalf("Failed to describe import: %s - %v", importID, err) } fmt.Printf("Import ID: %s, Status: %s", importDesc.Id, importDesc.Status) } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://{INDEX_HOST}/bulk/imports/101" \ -H 'Api-Key: $YOUR_API_KEY' \ -H 'X-Pinecone-Api-Version: 2025-10' ``` The response contains the import details, including the import `status`, `percent_complete`, and `records_imported`: ```json Response theme={null} { "id": "101", "uri": "s3://example_bucket/import", "status": "InProgress", "created_at": "2024-08-19T20:49:00.754Z", "finished_at": "2024-08-19T20:49:00.754Z", "percent_complete": 42.2, "records_imported": 1000000 } ``` If the import fails, the response contains an `error` field with the reason for the failure. See the [Troubleshooting](#troubleshooting) section for more information. ```json Response theme={null} { "id": "102", "uri": "s3://example_bucket/import", "status": "Failed", "percent_complete": 0.0, "records_imported": 0, "created_at": "2025-08-21T11:29:47.886797+00:00", "error": "User error: The namespace \"namespace1\" already exists. Imports are only allowed into nonexistent namespaces.", "finished_at": "2025-08-21T11:30:05.506423+00:00" } ``` ## Manage imports ### List imports Use the [`list_imports`](/reference/api/latest/data-plane/list_imports) operation to list all of the recent and ongoing imports. By default, the operation returns up to 100 imports per page. If the `limit` parameter is passed, the operation returns up to that number of imports per page instead. For example, if `limit=3`, up to 3 imports are returned per page. Whenever there are additional imports to return, the response includes a `pagination_token` for fetching the next page of imports. When using the Python SDK, `list_import` paginates automatically. ```python Python theme={null} from pinecone import Pinecone, ImportErrorMode pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") # List using a generator that handles pagination for i in index.list_imports(): print(f"id: {i.id} status: {i.status}") # List using a generator that fetches all results at once operations = list(index.list_imports()) print(operations) ``` ```json Response theme={null} { "data": [ { "id": "1", "uri": "s3://BUCKET_NAME/PATH/TO/DIR", "status": "Pending", "started_at": "2024-08-19T20:49:00.754Z", "finished_at": "2024-08-19T20:49:00.754Z", "percent_complete": 42.2, "records_imported": 1000000 } ], "pagination": { "next": "Tm90aGluZyB0byBzZWUgaGVyZQo=" } } ``` You can view the list of imports for an index in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes/). Select the index and navigate to the **Imports** tab. When using the Node.js SDK, Java SDK, Go SDK, or REST API to list recent and ongoing imports, you must manually fetch each page of results. To view the next page of results, include the `paginationToken` provided in the response. ```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/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const results = await index.listImports({ limit: 10, paginationToken: 'Tm90aGluZyB0byBzZWUgaGVyZQo' }); console.log(results); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import io.pinecone.clients.AsyncIndex; import org.openapitools.db_data.client.ApiException; import org.openapitools.db_data.client.model.ListImportsResponse; public class ListImports { public static void main(String[] args) throws ApiException { // Initialize a Pinecone client with your API key Pinecone pinecone = new Pinecone.Builder("YOUR_API_KEY").build(); // Get async imports connection object AsyncIndex asyncIndex = pinecone.getAsyncIndexConnection("docs-example"); // List imports ListImportsResponse response = asyncIndex.listImports(10, "Tm90aGluZyB0byBzZWUgaGVyZQo"); System.out.println(response); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } limit := int32(10) firstImportPage, err := idxConnection.ListImports(ctx, &limit, nil) if err != nil { log.Fatalf("Failed to list imports: %v", err) } fmt.Printf("First page of imports: %+v", firstImportPage.Imports) paginationToken := firstImportPage.NextPaginationToken nextImportPage, err := idxConnection.ListImports(ctx, &limit, paginationToken) if err != nil { log.Fatalf("Failed to list imports: %v", err) } fmt.Printf("Second page of imports: %+v", nextImportPage.Imports) } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/bulk/imports?paginationToken==Tm90aGluZyB0byBzZWUgaGVyZQo" \ -H 'Api-Key: $YOUR_API_KEY' \ -H 'X-Pinecone-Api-Version: 2025-10' ``` ### Cancel an import The [`cancel_import`](/reference/api/latest/data-plane/cancel_import) operation cancels an import if it is not yet finished. It has no effect if the import is already complete. ```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/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.cancel_import(id="101") ``` ```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/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") await index.cancelImport(id='101'); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import io.pinecone.clients.AsyncIndex; import org.openapitools.db_data.client.ApiException; public class CancelImport { public static void main(String[] args) throws ApiException { // Initialize a Pinecone client with your API key Pinecone pinecone = new Pinecone.Builder("YOUR_API_KEY").build(); // Get async imports connection object AsyncIndex asyncIndex = pinecone.getAsyncIndexConnection("docs-example"); // Cancel import asyncIndex.cancelImport("2"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } importID := "101" err = idxConnection.CancelImport(ctx, importID) if err != nil { log.Fatalf("Failed to cancel import: %s", importID) } importDesc, err := idxConnection.DescribeImport(ctx, importID) if err != nil { log.Fatalf("Failed to describe import: %s - %v", importID, err) } } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X DELETE "https://{INDEX_HOST}/bulk/imports/101" \ -H 'Api-Key: $YOUR_API_KEY' \ -H "X-Pinecone-Api-Version: 2025-10" ``` ```json Response theme={null} {} ``` You can cancel your import using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/import). To cancel an ongoing import, select the index you are importing into and navigate to the **Imports** tab. Then, click the **ellipsis (...) menu > Cancel**. ## Import limits If your import exceeds these limits, you'll get an error specifying the limit exceeded. See [Troubleshooting](/guides/index-data/import-data#troubleshooting) for details. | Metric | Limit | | :-------------------------------------------- | :-------- | | Max namespaces per import | 10,000 | | Max total input data size (on-demand indexes) | 1 TB | | Max total input data size (DRN indexes) | Unlimited | | Max files per import | 100,000 | | Max size per file | 10 GB | The total input data size limit does not apply to indexes with [dedicated read nodes](/guides/index-data/dedicated-read-nodes). Bulk import supports indexes without a schema definition (Parquet files) and indexes with document schemas ([JSONL files](/guides/search/full-text-search#bulk-import)). Semantic-text (auto-embedded) fields are not yet supported in document schemas. Also: * You cannot import data from an AWS S3 bucket into a Pinecone index hosted on GCP or Azure. * You cannot import data from S3 Express One Zone storage. * You cannot import data into an existing namespace. * When importing data into the `__default__` namespace of an index, the default namespace must be empty. * Each import takes at least 10 minutes to complete. * When importing into an [index with integrated embedding](/guides/index-data/indexing-overview#vector-embedding), records must contain vectors, not text. To add records with text, you must use [upsert](/guides/index-data/upsert-data). ## Troubleshooting When an import fails, you'll see an error message with the reason for the failure in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/import) or in the response to the [describe an import](/reference/api/latest/data-plane/describe_import) operation. You cannot import data into an existing namespace. If your import directory structure contains a folder with the name of an existing namespace in your index, the import will fail with the following error: ``` User error: The namespace "example-namespace" already exists. Imports are only allowed into nonexistent namespaces. ``` To fix this, rename the folder to use a namespace name that does not yet exist. In object storage, your directory structure must be as follows: ``` example_bucket/ --/imports/ ----/example_namespace1/ ------0.parquet ------1.parquet ------2.parquet ------3.parquet ----/example_namespace2/ ------4.parquet ------5.parquet ------6.parquet ------7.parquet ``` If a Parquet file is not nested under a namespace subdirectory, the import will fail with the following error: ``` User error: \"test-import/0.parquet\": No namespace detected. Each file should be nested under a subdirectory of the URI prefix. This indicates which namespace it should be imported into. ``` To fix this, move the Parquet file to a namespace subdirectory. Each namespace subdirectory must contain Parquet files with data to import. If a namespace subdirectory does not include Parquet files, the import will fail with the following error: ``` User error: No Parquet files found under \"gs://example_bucket/imports\". Files must be stored with the specified bucket prefix. ``` To fix this, add Parquet files to the namespace subdirectory. In your [start import](/reference/api/latest/data-plane/start_import) request, the import `uri` must specify only the bucket and import directory containing the namespaces and Parquet files you want to import. If the `uri` also contains a namespaces directory or a Parquet filename, the import will fail with the following error: ``` User error: \"test-import/0.parquet\": It looks like you specified a complete path to a parquet file as the URI prefix to import from. Note that the URI prefix should give an ancestor directory with subdirectories to specify each namespace to import into. See https://docs.pinecone.io/guides/data/understanding-imports#directory-structure. ``` To fix this, remove the namespaces directory or Parquet filename from the `uri`. When a Parquet file is not formatted correctly, the import will fail with a message like one of the following: ```shell File schema errors theme={null} Missing required column \"{0}\" Unsupported column \"{0}\" ``` ```shell File corruption errors theme={null} Parquet footer could not be parsed. Are you sure this is valid parquet? ``` ```shell Type errors theme={null} The expected data type for column \"{column}\" is \"{expected}\", but got \"{given}\" The expected data type for metadata is a JSON encoded string in UTF-8 format, but got \"{given}\" ``` These errors are returned for both `continue` and `abort` error modes. To fix these errors, check the specific error message and follow the instructions in the [Prepare your data](#prepare-your-data) section. When the `error_mode` is `abort` and a file contains invalid records, the import will stop processing on the first invalid record and return an error message identifying the file name and row: ``` User error: error reading record (file \"/0.parquet\", row 0): ``` This will be followed by an error message identifying the specific issue. For example: ```shell Missing values theme={null} missing required values in column \"{column}\" ``` ```shell Invalid metadata theme={null} Failed to parse metadata: {msg} ``` ```shell Invalid vectors theme={null} Upserting dense vectors is not supported for indexes that store only sparse vectors ``` When the `error_mode` is `continue`, the import will skip individual invalid records. However, if all records are invalid and skipped (for example, the vector type in the file does not match the vector type of the index), the import will fail with a general message: ``` User error: No vectors added, all rows were skipped for namespace: example-namespace ``` To fix these errors, check the specific error message and follow the instructions in the [Prepare your data](#prepare-your-data) section. When your import contains duplicate vectors (records with identical vector values), the duplicates are marked as skipped and not imported. Only one occurrence of each unique vector is added to the index. This applies to both `continue` and `abort` error modes: * With `abort`: The import fails when it encounters a duplicate vector within the import. * With `continue`: The import proceeds, skipping duplicate records silently. **Example scenario:** If your Parquet file contains: ```parquet theme={null} id | values ---|--------- 1 | [0.1, 0.2, 0.3] 2 | [0.1, 0.2, 0.3] ← Duplicate of record 1, will be skipped 3 | [0.4, 0.5, 0.6] ``` Only records 1 and 3 will be imported. To prevent this from happening, deduplicate your source data before creating Parquet files by removing records with identical vector values. On-demand indexes have a maximum total input data size of 1 TB per import. If your import exceeds this limit, it will fail with the following error: ``` Import ({size} GB) exceeds the maximum input data size of 1000 GB for on-demand. Consider using Dedicated Read Nodes (DRN) for larger index sizes, or contact support for your use-case. ``` To fix this, either reduce the total size of your import to under 1 TB, use an index with [dedicated read nodes](/guides/index-data/dedicated-read-nodes) (which have no total data size limit for imports), or [contact support](https://app.pinecone.io/organizations/-/settings/support/ticket). ## See also * [Integrate with Amazon S3](/guides/operations/integrations/integrate-with-amazon-s3) * [Integrate with Google Cloud Storage](/guides/operations/integrations/integrate-with-google-cloud-storage) * [Integrate with Azure Blob Storage](/guides/operations/integrations/integrate-with-azure-blob-storage) * [Pinecone's pricing](https://www.pinecone.io/pricing/) # Indexing overview Source: https://docs.pinecone.io/guides/index-data/indexing-overview Learn how indexing works in Pinecone: serverless indexes, document schemas, namespaces, integrated embedding, and metadata filtering. ## Indexes In Pinecone, you store data in indexes. A serverless index holds your data as [documents](/guides/get-started/concepts#document) or [records](/guides/get-started/concepts#record), depending on how the index was created: an index created with a document schema holds documents, while an index created with a dense or sparse vector type holds records. A single index with a document schema can mix multiple ranking field types: a `dense_vector` field for [semantic search](/guides/search/semantic-search), a `sparse_vector` field for [sparse-vector retrieval](/guides/search/lexical-search), and one or more `string` fields with `full_text_search` enabled for [full-text search](/guides/search/full-text-search) with BM25 and Lucene queries. Any other fields you upsert are stored as metadata, automatically indexed for filtering — no schema declaration required. One index per use case is the typical pattern. Because a document can combine vectors, text, and metadata in the same record, a single index often covers what previously required two — pick the ranking signal per query with `score_by`. ### 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: ```json theme={null} { "score_by": [{ "type": "text", "field": "body", "query": "machine learning" }], "top_k": 10 } ``` Reach for full-text search when relevance comes down to specific tokens appearing in both the query and the data: SKUs, error messages, code, named entities. For semantic similarity over natural-language queries, see [Indexes with dense vectors](#indexes-with-dense-vectors); for retrieval with a learned sparse encoder, see [Indexes with sparse vectors](#indexes-with-sparse-vectors). Learn more: * [Full-text search guide](/guides/search/full-text-search) * [Schema definition](/guides/search/full-text-search#schema-definition) * [Upsert documents](/guides/search/full-text-search#upsert-documents) ### Indexes with dense vectors 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](/guides/get-started/concepts#dense-vector). Learn more: * [Create an index for dense vectors](/guides/index-data/create-an-index#create-an-index-for-dense-vectors) * [Upsert dense vectors](/guides/index-data/upsert-data#upsert-dense-vectors) * [Semantic search](/guides/search/semantic-search) ### Indexes with sparse vectors 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 — **sparse-vector lexical search**. Sparse vectors come from a sparse embedding model. Pinecone hosts [`pinecone-sparse-english-v0`](/models/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](/guides/get-started/concepts#index-with-sparse-vectors). Learn more: * [Create an index for sparse vectors](/guides/index-data/create-an-index#create-an-index-for-sparse-vectors) * [Upsert sparse vectors](/guides/index-data/upsert-data#upsert-sparse-vectors) * [Lexical search](/guides/search/lexical-search) #### Limitations Indexes of sparse vectors have the following limitations: * Max non-zero values per sparse vector: 1000 * 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: 1000 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: 4MB Semantic search can miss exact keyword matches, while lexical search can miss semantically related results. To get the best of both, use [hybrid search](/guides/search/hybrid-search) — combine a lexical signal (BM25 or sparse) with a dense signal at query time, often with reranking. ## Namespaces Within an index, records are partitioned into namespaces, and all [upserts](/guides/index-data/upsert-data), [queries](/guides/search/search-overview), 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](/guides/index-data/implement-multitenancy) for end-to-end guidance. * **Faster queries:** When you divide records into namespaces in a logical way, you speed up queries by ensuring only relevant records are scanned. The same applies to fetching records, listing record IDs, and other data operations. Namespaces are created automatically during [upsert](/guides/index-data/upsert-data). If a namespace doesn't exist, it is created implicitly. [Namespaces per serverless index](/reference/api/database-limits#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](https://app.pinecone.io/organizations/-/settings/support/ticket). ## Vector embedding [Dense vectors](/guides/get-started/concepts#dense-vector) and [sparse vectors](/guides/get-started/concepts#sparse-vector) are the basic units of data in Pinecone and what Pinecone was specially designed to store and work with. Dense vectors represents the semantics of data such as text, images, and audio recordings, while sparse vectors represent documents or queries in a way that captures keyword information. To transform data into vector format, you use an embedding model. You can either use Pinecone's integrated embedding models to convert your source data to vectors automatically, or you can use an external embedding model and bring your own vectors to Pinecone. ### Integrated embedding 1. [Create an index](/guides/index-data/create-an-index) that is integrated with one of Pinecone's [hosted embedding models](/guides/index-data/create-an-index#embedding-models). 2. [Upsert](/guides/index-data/upsert-data) your source text. Pinecone uses the integrated model to convert the text to vectors automatically. 3. [Search](/guides/search/search-overview) 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](/guides/manage-data/update-data) or [importing](/guides/index-data/import-data) with text. ### Bring your own vectors 1. Use an embedding model to convert your text to vectors. The model can be [hosted by Pinecone](/reference/api/latest/inference/generate-embeddings) or an external provider. 2. [Create an index](/guides/index-data/create-an-index) that matches the characteristics of the model. 3. [Upsert](/guides/index-data/upsert-data) your vectors directly. 4. Use the same external embedding model to convert a query to a vector. 5. [Search](/guides/search/search-overview) with your query vector directly. ## Data ingestion To control costs when ingesting large datasets (10,000,000+ records), use [import](/guides/index-data/import-data) instead of upsert. There are two ways to ingest data into an index: * [Importing from object storage](/guides/index-data/import-data) is the most efficient and cost-effective way to load large numbers of records into an index. You store your data as Parquet files in object storage, integrate your object storage with Pinecone, and then start an asynchronous, long-running operation that imports and indexes your records. * [Upserting](/guides/index-data/upsert-data) is intended for ongoing writes to an index. [Batch upserting](/guides/index-data/upsert-data#upsert-in-batches) can improve throughput performance and is a good option for larger numbers of records (up to 1000 per batch) if you cannot work around import's current limitations. ## Metadata Every [record](/guides/get-started/concepts#record) in an index must contain an ID and a vector. In addition, you can include metadata key-value pairs to store additional information or context. When you query the index, you can then include a [metadata filter](/guides/search/filter-by-metadata) to limit the search to records matching a filter expression. Searches without metadata filters do not 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** ```json Valid metadata theme={null} { "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 1, "chunk_text": "First chunk of the document content...", "is_public": true, "tags": ["beginner", "database", "vector-db"], "scores": ["85", "92"] } ``` ```json Invalid metadata theme={null} { "document": { // Nested JSON objects are not supported "document_id": "document1", "document_title": "Introduction to Vector Databases", }, "$chunk_number": 1, // Keys must not start with a `$` "chunk_text": null, // Null values are not supported "is_public": true, "tags": ["beginner", "database", "vector-db"], "scores": [85, 92] // Lists of non-strings are not supported } ``` ### Metadata size Pinecone supports 40KB of metadata per record. ### Metadata filter expressions Pinecone's filtering language supports the following operators: | Operator | Function | Supported types | | :-------- | :------------------------------------------------------------------------------------------------------------------------- | :---------------------- | | `$eq` | Matches with metadata values that are equal to a specified value. Example: `{"genre": {"$eq": "documentary"}}` | Number, string, boolean | | `$ne` | Matches with metadata values that are not equal to a specified value. Example: `{"genre": {"$ne": "drama"}}` | Number, string, boolean | | `$gt` | Matches with metadata values that are greater than a specified value. Example: `{"year": {"$gt": 2019}}` | Number | | `$gte` | Matches with metadata values that are greater than or equal to a specified value. Example:`{"year": {"$gte": 2020}}` | Number | | `$lt` | Matches with metadata values that are less than a specified value. Example: `{"year": {"$lt": 2020}}` | Number | | `$lte` | Matches with metadata values that are less than or equal to a specified value. Example: `{"year": {"$lte": 2020}}` | Number | | `$in` | Matches with metadata values that are in a specified array. Example: `{"genre": {"$in": ["comedy", "documentary"]}}` | String, number | | `$nin` | Matches with metadata values that are not in a specified array. Example: `{"genre": {"$nin": ["comedy", "documentary"]}}` | String, number | | `$exists` | Matches with the specified metadata field. Example: `{"genre": {"$exists": true}}` | Number, string, boolean | | `$and` | Joins query clauses with a logical `AND`. Example: `{"$and": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}` | - | | `$or` | Joins query clauses with a logical `OR`. Example: `{"$or": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}` | - | Only `$and` and `$or` are allowed at the top level of the query expression. 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](/reference/api/database-limits#metadata-filter-limits). For example, the following has a `"genre"` metadata field with a list of strings: ```JSON JSON theme={null} { "genre": ["comedy", "documentary"] } ``` This means `"genre"` takes on both values, and requests with the following filters will match: ```JSON JSON theme={null} {"genre":"comedy"} {"genre": {"$in":["documentary","action"]}} {"$and": [{"genre": "comedy"}, {"genre":"documentary"}]} ``` However, requests with the following filter will **not** match: ```JSON JSON theme={null} { "$and": [{ "genre": "comedy" }, { "genre": "drama" }] } ``` Additionally, requests with the following filters will **not** match because they are invalid. They will result in a compilation error: ```json JSON theme={null} # INVALID QUERY: {"genre": ["comedy", "documentary"]} ``` ```json JSON theme={null} # INVALID QUERY: {"genre": {"$eq": ["comedy", "documentary"]}} ``` # Upsert records Source: https://docs.pinecone.io/guides/index-data/upsert-data Upsert dense, sparse, and text records into Pinecone indexes, batch upserts for higher throughput, and partition data with namespaces. This page shows you how to upsert records into a namespace in an index. [Namespaces](/guides/index-data/indexing-overview#namespaces) let you partition records within an index and are essential for [implementing multitenancy](/guides/index-data/implement-multitenancy) when you need to isolate the data of each customer/user. If a record ID already exists, upserting overwrites the entire record. To change only part of a record, [update ](/guides/manage-data/update-data) the record. Upserts consume [write units (WUs)](/guides/manage-cost/understanding-cost#write-units). See [Understanding cost](/guides/manage-cost/understanding-cost#upsert) for how upsert cost is calculated. To control costs when ingesting large datasets (10,000,000+ records), use [import](/guides/index-data/import-data) instead of upsert. ## Upsert dense vectors Upserting text is supported only for [indexes with integrated embedding](/guides/index-data/indexing-overview#integrated-embedding). To upsert source text into an [index of dense vectors with integrated embedding](/guides/index-data/create-an-index#create-an-index-for-dense-vectors), use the [`upsert_records`](/reference/api/latest/data-plane/upsert_records) operation. Pinecone converts the text to dense vectors automatically using the hosted dense embedding model associated with the index. * Specify the [`namespace`](/guides/index-data/indexing-overview#namespaces) to upsert into. If the namespace doesn't exist, it is created. To use the default namespace, set the namespace to `"__default__"`. * Format your input data as records, each with the following: * An `_id` field with a unique record identifier for the index namespace. `id` can be used as an alias for `_id`. * A field with the source text to convert to a vector. This field must match the `field_map` specified in the index. * Additional fields are stored as record [metadata](/guides/index-data/indexing-overview#metadata) and can be returned in search results or used to [filter search results](/guides/search/filter-by-metadata). For example, the following code converts the sentences in the `chunk_text` fields to dense vectors and then upserts them into `example-namespace` in an example index. The additional `category` field is stored as metadata. ```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/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") # Upsert records into a namespace # `chunk_text` fields are converted to dense vectors # `category` fields are stored as metadata index.upsert_records( "example-namespace", [ { "_id": "rec1", "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.", "category": "digestive system", }, { "_id": "rec2", "chunk_text": "Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today.", "category": "cultivation", }, { "_id": "rec3", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.", "category": "immune system", }, { "_id": "rec4", "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.", "category": "endocrine system", }, ] ) ``` ```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/manage-data/target-an-index const namespace = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace"); // Upsert records into a namespace // `chunk_text` fields are converted to dense vectors // `category` is stored as metadata await namespace.upsertRecords([ { "_id": "rec1", "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.", "category": "digestive system", }, { "_id": "rec2", "chunk_text": "Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today.", "category": "cultivation", }, { "_id": "rec3", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.", "category": "immune system", }, { "_id": "rec4", "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.", "category": "endocrine system", } ]); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import org.openapitools.db_data.client.ApiException; import java.util.*; public class UpsertText { public static void main(String[] args) throws ApiException { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "integrated-dense-java"); ArrayList> upsertRecords = new ArrayList<>(); HashMap record1 = new HashMap<>(); record1.put("_id", "rec1"); record1.put("category", "digestive system"); record1.put("chunk_text", "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut."); HashMap record2 = new HashMap<>(); record2.put("_id", "rec2"); record2.put("category", "cultivation"); record2.put("chunk_text", "Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today."); HashMap record3 = new HashMap<>(); record3.put("_id", "rec3"); record3.put("category", "immune system"); record3.put("chunk_text", "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases."); HashMap record4 = new HashMap<>(); record4.put("_id", "rec4"); record4.put("category", "endocrine system"); record4.put("chunk_text", "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes."); upsertRecords.add(record1); upsertRecords.add(record2); upsertRecords.add(record3); upsertRecords.add(record4); index.upsertRecords("example-namespace", upsertRecords); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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/manage-data/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) } // Upsert records into a namespace // `chunk_text` fields are converted to dense vectors // `category` is stored as metadata records := []*pinecone.IntegratedRecord{ { "_id": "rec1", "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.", "category": "digestive system", }, { "_id": "rec2", "chunk_text": "Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today.", "category": "cultivation", }, { "_id": "rec3", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.", "category": "immune system", }, { "_id": "rec4", "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.", "category": "endocrine system", }, } err = idxConnection.UpsertRecords(ctx, records) if err != nil { log.Fatalf("Failed to upsert vectors: %v", err) } } ``` ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index INDEX_HOST="INDEX_HOST" NAMESPACE="YOUR_NAMESPACE" PINECONE_API_KEY="YOUR_API_KEY" # Upsert records into a namespace # `chunk_text` fields are converted to dense vectors # `category` is stored as metadata curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/upsert" \ -H "Content-Type: application/x-ndjson" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{"_id": "rec1", "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.", "category": "digestive system"} {"_id": "rec2", "chunk_text": "Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today.", "category": "cultivation"} {"_id": "rec3", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.", "category": "immune system"} {"_id": "rec4", "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.", "category": "endocrine system"}' ``` To upsert dense vectors into an [index of dense vectors](/guides/index-data/create-an-index#create-an-index-for-dense-vectors), use the [`upsert`](/reference/api/latest/data-plane/upsert) operation as follows: * Specify the [`namespace`](/guides/index-data/indexing-overview#namespaces) to upsert into. If the namespace doesn't exist, it is created. To use the default namespace, set the namespace to `"__default__"`. * Format your input data as records, each with the following: * An `id` field with a unique record identifier for the index namespace. * A `values` field with the dense vector values. * Optionally, a `metadata` field with [key-value pairs](/guides/index-data/indexing-overview#metadata) to store additional information or context. When you query the index, you can use metadata to [filter search results](/guides/search/filter-by-metadata). ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.upsert( vectors=[ { "id": "A", "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1], "metadata": {"genre": "comedy", "year": 2020} }, { "id": "B", "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2], "metadata": {"genre": "documentary", "year": 2019} }, { "id": "C", "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3], "metadata": {"genre": "comedy", "year": 2019} }, { "id": "D", "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4], "metadata": {"genre": "drama"} } ], namespace="example-namespace" ) ``` ```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/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const records = [ { id: 'A', values: [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1], metadata: { genre: "comedy", year: 2020 }, }, { id: 'B', values: [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2], metadata: { genre: "documentary", year: 2019 }, }, { id: 'C', values: [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3], metadata: { genre: "comedy", year: 2019 }, }, { id: 'D', values: [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4], metadata: { genre: "drama" }, } ] await index.namespace('example-namespace').upsert({ records: records }); ``` ```java Java theme={null} import com.google.protobuf.Struct; import com.google.protobuf.Value; import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import java.util.Arrays; import java.util.List; public class UpsertExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); List values1 = Arrays.asList(0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f); List values2 = Arrays.asList(0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f); List values3 = Arrays.asList(0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f); List values4 = Arrays.asList(0.4f, 0.4f, 0.4f, 0.4f, 0.4f, 0.4f, 0.4f, 0.4f); Struct metaData1 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("comedy").build()) .putFields("year", Value.newBuilder().setNumberValue(2020).build()) .build(); Struct metaData2 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("documentary").build()) .putFields("year", Value.newBuilder().setNumberValue(2019).build()) .build(); Struct metaData3 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("comedy").build()) .putFields("year", Value.newBuilder().setNumberValue(2019).build()) .build(); Struct metaData4 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("drama").build()) .build(); index.upsert("A", values1, null, null, metaData1, 'example-namespace'); index.upsert("B", values2, null, null, metaData2, 'example-namespace'); index.upsert("C", values3, null, null, metaData3, 'example-namespace'); index.upsert("D", values4, null, null, metaData4, 'example-namespace'); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" "google.golang.org/protobuf/types/known/structpb" ) 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/manage-data/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) } metadataMap1 := map[string]interface{}{ "genre": "comedy", "year": 2020, } metadata1, err := structpb.NewStruct(metadataMap1) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } metadataMap2 := map[string]interface{}{ "genre": "documentary", "year": 2019, } metadata2, err := structpb.NewStruct(metadataMap2) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } metadataMap3 := map[string]interface{}{ "genre": "comedy", "year": 2019, } metadata3, err := structpb.NewStruct(metadataMap3) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } metadataMap4 := map[string]interface{}{ "genre": "drama", } metadata4, err := structpb.NewStruct(metadataMap4) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } vectors := []*pinecone.Vector{ { Id: "A", Values: []float32{0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1}, Metadata: metadata1, }, { Id: "B", Values: []float32{0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2}, Metadata: metadata2, }, { Id: "C", Values: []float32{0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3}, Metadata: metadata3, }, { Id: "D", Values: []float32{0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4}, Metadata: metadata4, }, } count, err := idxConnection.UpsertVectors(ctx, vectors) if err != nil { log.Fatalf("Failed to upsert vectors: %v", err) } else { fmt.Printf("Successfully upserted %d vector(s)!\n", count) } } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/vectors/upsert" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "vectors": [ { "id": "A", "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1], "metadata": {"genre": "comedy", "year": 2020} }, { "id": "B", "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2], "metadata": {"genre": "documentary", "year": 2019} }, { "id": "C", "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3], "metadata": {"genre": "comedy", "year": 2019} }, { "id": "D", "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4], "metadata": {"genre": "drama"} } ], "namespace": "example-namespace" }' ``` ## Upsert sparse vectors Sparse-vector upsert is the right choice when your data is encoded by a learned sparse model (for example, [`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0)) or when your application owns the sparse-vector representation directly. For BM25-style keyword search over raw text with no model to manage, see [Upsert documents](#upsert-documents). Upserting text is supported only for [indexes with integrated embedding](/guides/index-data/indexing-overview#integrated-embedding). To upsert source text into an [index of sparse vectors with integrated embedding](/guides/index-data/create-an-index#create-an-index-for-sparse-vectors), use the [`upsert_records`](/reference/api/latest/data-plane/upsert_records) operation. Pinecone converts the text to sparse vectors automatically using the hosted sparse embedding model associated with the index. * Specify the [`namespace`](/guides/index-data/indexing-overview#namespaces) to upsert into. If the namespace doesn't exist, it is created. To use the default namespace, set the namespace to `"__default__"`. * Format your input data as records, each with the following: * An `_id` field with a unique record identifier for the index namespace. `id` can be used as an alias for `_id`. * A field with the source text to convert to a vector. This field must match the `field_map` specified in the index. * Additional fields are stored as record [metadata](/guides/index-data/indexing-overview#metadata) and can be returned in search results or used to [filter search results](/guides/search/filter-by-metadata). For example, the following code converts the sentences in the `chunk_text` fields to sparse vectors and then upserts them into `example-namespace` in an example index. The additional `category` and `quarter` fields are stored as metadata. ```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/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") # Upsert records into a namespace # `chunk_text` fields are converted to sparse vectors # `category` and `quarter` fields are stored as metadata index.upsert_records( "example-namespace", [ { "_id": "vec1", "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "category": "technology", "quarter": "Q3" }, { "_id": "vec2", "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4" }, { "_id": "vec3", "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.", "category": "technology", "quarter": "Q3" }, { "_id": "vec4", "chunk_text": "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.", "category": "technology", "quarter": "Q4" } ] ) time.sleep(10) # Wait for the upserted vectors to be indexed ``` ```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/manage-data/target-an-index const namespace = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace"); // Upsert records into a namespace // `chunk_text` fields are converted to sparse vectors // `category` and `quarter` fields are stored as metadata await namespace.upsertRecords([ { "_id": "vec1", "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "category": "technology", "quarter": "Q3" }, { "_id": "vec2", "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4" }, { "_id": "vec3", "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.", "category": "technology", "quarter": "Q3" }, { "_id": "vec4", "chunk_text": "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.", "category": "technology", "quarter": "Q4" } ]); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import org.openapitools.db_data.client.ApiException; import java.util.*; public class UpsertText { public static void main(String[] args) throws ApiException { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "integrated-sparse-java"); ArrayList> upsertRecords = new ArrayList<>(); HashMap record1 = new HashMap<>(); record1.put("_id", "rec1"); record1.put("category", "digestive system"); record1.put("chunk_text", "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut."); HashMap record2 = new HashMap<>(); record2.put("_id", "rec2"); record2.put("category", "cultivation"); record2.put("chunk_text", "Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today."); HashMap record3 = new HashMap<>(); record3.put("_id", "rec3"); record3.put("category", "immune system"); record3.put("chunk_text", "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases."); HashMap record4 = new HashMap<>(); record4.put("_id", "rec4"); record4.put("category", "endocrine system"); record4.put("chunk_text", "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes."); upsertRecords.add(record1); upsertRecords.add(record2); upsertRecords.add(record3); upsertRecords.add(record4); index.upsertRecords("example-namespace", upsertRecords); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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/manage-data/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) } // Upsert records into a namespace // `chunk_text` fields are converted to sparse vectors // `category` and `quarter` fields are stored as metadata records := []*pinecone.IntegratedRecord{ { "_id": "vec1", "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "category": "technology", "quarter": "Q3", }, { "_id": "vec2", "chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4", }, { "_id": "vec3", "chunk_text": "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.", "category": "technology", "quarter": "Q3", }, { "_id": "vec4", "chunk_text": "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.", "category": "technology", "quarter": "Q4", }, } err = idxConnection.UpsertRecords(ctx, records) if err != nil { log.Fatalf("Failed to upsert vectors: %v", err) } } ``` ```shell curl theme={null} INDEX_HOST="INDEX_HOST" NAMESPACE="YOUR_NAMESPACE" PINECONE_API_KEY="YOUR_API_KEY" curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/upsert" \ -H "Content-Type: application/x-ndjson" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "_id": "vec1", "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "category": "technology", "quarter": "Q3" } { "_id": "vec2", "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4" } { "_id": "vec3", "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.", "category": "technology", "quarter": "Q3" } { "_id": "vec4", "chunk_text": "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.", "category": "technology", "quarter": "Q4" }' ``` To upsert sparse vectors into an [index of sparse vectors](/guides/index-data/create-an-index#create-an-index-for-sparse-vectors), use the [`upsert`](/reference/api/latest/data-plane/upsert) operation as follows: * Specify the [`namespace`](/guides/index-data/indexing-overview#namespaces) to upsert into. If the namespace doesn't exist, it is created. To use the default namespace, set the namespace to `"__default__"`. * Format your input data as records, each with the following: * An `id` field with a unique record identifier for the index namespace. * A `sparse_values` field with the sparse vector values and indices. * Optionally, a `metadata` field with [key-value pairs](/guides/index-data/indexing-overview#metadata) to store additional information or context. When you query the index, you can use metadata to [filter search results](/guides/search/filter-by-metadata). For example, the following code upserts sparse vector representations of sentences related to the term "apple", with the source text and additional fields stored as metadata: ```python Python theme={null} from pinecone import Pinecone, SparseValues, Vector pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.upsert( namespace="example-namespace", vectors=[ { "id": "vec1", "sparse_values": { "values": [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688], "indices": [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191] }, "metadata": { "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "category": "technology", "quarter": "Q3" } }, { "id": "vec2", "sparse_values": { "values": [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469], "indices": [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697] }, "metadata": { "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4" } }, { "id": "vec3", "sparse_values": { "values": [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094], "indices": [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697] }, "metadata": { "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", "category": "technology", "quarter": "Q3" } }, { "id": "vec4", "sparse_values": { "values": [0.73046875, 0.46972656, 2.84375, 5.2265625, 3.3242188, 1.9863281, 0.9511719, 0.5019531, 4.4257812, 3.4277344, 0.41308594, 4.3242188, 2.4179688, 3.1757812, 1.0224609, 2.0585938, 2.5859375], "indices": [131900689, 152217691, 441495248, 1640781426, 1851149807, 2263326288, 2502307765, 2641553256, 2684780967, 2966813704, 3162218338, 3283104238, 3488055477, 3530642888, 3888762515, 4152503047, 4177290673] }, "metadata": { "chunk_text": "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.", "category": "technology", "quarter": "Q4" } } ] ) ``` ```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/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") await index.namespace('example-namespace').upsert({ records: [ { id: 'vec1', sparseValues: { indices: [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191], values: [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688] }, metadata: { chunk_text: 'AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.', category: 'technology', quarter: 'Q3' } }, { id: 'vec2', sparseValues: { indices: [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697], values: [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469] }, metadata: { chunk_text: "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.", category: 'technology', quarter: 'Q4' } }, { id: 'vec3', sparseValues: { indices: [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697], values: [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094] }, metadata: { chunk_text: "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", category: 'technology', quarter: 'Q3' } }, { id: 'vec4', sparseValues: { indices: [131900689, 152217691, 441495248, 1640781426, 1851149807, 2263326288, 2502307765, 2641553256, 2684780967, 2966813704, 3162218338, 3283104238, 3488055477, 3530642888, 3888762515, 4152503047, 4177290673], values: [0.73046875, 0.46972656, 2.84375, 5.2265625, 3.3242188, 1.9863281, 0.9511719, 0.5019531, 4.4257812, 3.4277344, 0.41308594, 4.3242188, 2.4179688, 3.1757812, 1.0224609, 2.0585938, 2.5859375] }, metadata: { chunk_text: 'AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.', category: 'technology', quarter: 'Q4' } } ] }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import io.pinecone.clients.Index; import com.google.protobuf.Struct; import com.google.protobuf.Value; import java.util.*; public class UpsertSparseVectors { public static void main(String[] args) throws InterruptedException { // Instantiate Pinecone class Pinecone pinecone = new Pinecone.Builder("YOUR_API)KEY").build(); Index index = pinecone.getIndexConnection("docs-example"); // Record 1 ArrayList indices1 = new ArrayList<>(Arrays.asList( 822745112L, 1009084850L, 1221765879L, 1408993854L, 1504846510L, 1596856843L, 1640781426L, 1656251611L, 1807131503L, 2543655733L, 2902766088L, 2909307736L, 3246437992L, 3517203014L, 3590924191L )); ArrayList values1 = new ArrayList<>(Arrays.asList( 1.7958984f, 0.41577148f, 2.828125f, 2.8027344f, 2.8691406f, 1.6533203f, 5.3671875f, 1.3046875f, 0.49780273f, 0.5722656f, 2.71875f, 3.0820312f, 2.5019531f, 4.4414062f, 3.3554688f )); Struct metaData1 = Struct.newBuilder() .putFields("chunk_text", Value.newBuilder().setStringValue("AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.").build()) .putFields("category", Value.newBuilder().setStringValue("technology").build()) .putFields("quarter", Value.newBuilder().setStringValue("Q3").build()) .build(); // Record 2 ArrayList indices2 = new ArrayList<>(Arrays.asList( 131900689L, 592326839L, 710158994L, 838729363L, 1304885087L, 1640781426L, 1690623792L, 1807131503L, 2066971792L, 2428553208L, 2548600401L, 2577534050L, 3162218338L, 3319279674L, 3343062801L, 3476647774L, 3485013322L, 3517203014L, 4283091697L )); ArrayList values2 = new ArrayList<>(Arrays.asList( 0.4362793f, 3.3457031f, 2.7714844f, 3.0273438f, 3.3164062f, 5.6015625f, 2.4863281f, 0.38134766f, 1.25f, 2.9609375f, 0.34179688f, 1.4306641f, 0.34375f, 3.3613281f, 1.4404297f, 2.2558594f, 2.2597656f, 4.8710938f, 0.5605469f )); Struct metaData2 = Struct.newBuilder() .putFields("chunk_text", Value.newBuilder().setStringValue("Analysts suggest that AAPL'\\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.").build()) .putFields("category", Value.newBuilder().setStringValue("technology").build()) .putFields("quarter", Value.newBuilder().setStringValue("Q4").build()) .build(); // Record 3 ArrayList indices3 = new ArrayList<>(Arrays.asList( 8661920L, 350356213L, 391213188L, 554637446L, 1024951234L, 1640781426L, 1780689102L, 1799010313L, 2194093370L, 2632344667L, 2641553256L, 2779594451L, 3517203014L, 3543799498L, 3837503950L, 4283091697L )); ArrayList values3 = new ArrayList<>(Arrays.asList( 2.6875f, 4.2929688f, 3.609375f, 3.0722656f, 2.1152344f, 5.78125f, 3.7460938f, 3.7363281f, 1.2695312f, 3.4824219f, 0.7207031f, 0.0826416f, 4.671875f, 3.7011719f, 2.796875f, 0.61621094f )); Struct metaData3 = Struct.newBuilder() .putFields("chunk_text", Value.newBuilder().setStringValue("AAPL'\\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production").build()) .putFields("category", Value.newBuilder().setStringValue("technology").build()) .putFields("quarter", Value.newBuilder().setStringValue("Q3").build()) .build(); // Record 4 ArrayList indices4 = new ArrayList<>(Arrays.asList( 131900689L, 152217691L, 441495248L, 1640781426L, 1851149807L, 2263326288L, 2502307765L, 2641553256L, 2684780967L, 2966813704L, 3162218338L, 3283104238L, 3488055477L, 3530642888L, 3888762515L, 4152503047L, 4177290673L )); ArrayList values4 = new ArrayList<>(Arrays.asList( 0.73046875f, 0.46972656f, 2.84375f, 5.2265625f, 3.3242188f, 1.9863281f, 0.9511719f, 0.5019531f, 4.4257812f, 3.4277344f, 0.41308594f, 4.3242188f, 2.4179688f, 3.1757812f, 1.0224609f, 2.0585938f, 2.5859375f )); Struct metaData4 = Struct.newBuilder() .putFields("chunk_text", Value.newBuilder().setStringValue("AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space").build()) .putFields("category", Value.newBuilder().setStringValue("technology").build()) .putFields("quarter", Value.newBuilder().setStringValue("Q4").build()) .build(); index.upsert("vec1", Collections.emptyList(), indices1, values1, metaData1, "example-namespace"); index.upsert("vec2", Collections.emptyList(), indices2, values2, metaData2, "example-namespace"); index.upsert("vec3", Collections.emptyList(), indices3, values3, metaData3, "example-namespace"); index.upsert("vec4", Collections.emptyList(), indices4, values4, metaData4, "example-namespace"); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" "google.golang.org/protobuf/types/known/structpb" ) 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/manage-data/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) } sparseValues1 := pinecone.SparseValues{ Indices: []uint32{822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191}, Values: []float32{1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688}, } metadataMap1 := map[string]interface{}{ "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones", "category": "technology", "quarter": "Q3", } metadata1, err := structpb.NewStruct(metadataMap1) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } sparseValues2 := pinecone.SparseValues{ Indices: []uint32{131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697}, Values: []float32{0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.560546}, } metadataMap2 := map[string]interface{}{ "chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4", } metadata2, err := structpb.NewStruct(metadataMap2) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } sparseValues3 := pinecone.SparseValues{ Indices: []uint32{8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697}, Values: []float32{2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094}, } metadataMap3 := map[string]interface{}{ "chunk_text": "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", "category": "technology", "quarter": "Q3", } metadata3, err := structpb.NewStruct(metadataMap3) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } sparseValues4 := pinecone.SparseValues{ Indices: []uint32{131900689, 152217691, 441495248, 1640781426, 1851149807, 2263326288, 2502307765, 2641553256, 2684780967, 2966813704, 3162218338, 3283104238, 3488055477, 3530642888, 3888762515, 4152503047, 4177290673}, Values: []float32{0.73046875, 0.46972656, 2.84375, 5.2265625, 3.3242188, 1.9863281, 0.9511719, 0.5019531, 4.4257812, 3.4277344, 0.41308594, 4.3242188, 2.4179688, 3.1757812, 1.0224609, 2.0585938, 2.5859375}, } metadataMap4 := map[string]interface{}{ "chunk_text": "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.", "category": "technology", "quarter": "Q4", } metadata4, err := structpb.NewStruct(metadataMap4) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } vectors := []*pinecone.Vector{ { Id: "vec1", SparseValues: &sparseValues1, Metadata: metadata1, }, { Id: "vec2", SparseValues: &sparseValues2, Metadata: metadata2, }, { Id: "vec3", SparseValues: &sparseValues3, Metadata: metadata3, }, { Id: "vec4", SparseValues: &sparseValues4, Metadata: metadata4, }, } count, err := idxConnection.UpsertVectors(ctx, vectors) if err != nil { log.Fatalf("Failed to upsert vectors: %v", err) } else { fmt.Printf("Successfully upserted %d vector(s)!\n", count) } } ``` ```shell curl theme={null} INDEX_HOST="INDEX_HOST" PINECONE_API_KEY="YOUR_API_KEY" curl "http://$INDEX_HOST/vectors/upsert" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "namespace": "example-namespace", "vectors": [ { "id": "vec1", "sparseValues": { "values": [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688], "indices": [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191] }, "metadata": { "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "category": "technology", "quarter": "Q3" } }, { "id": "vec2", "sparseValues": { "values": [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469], "indices": [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697] }, "metadata": { "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4" } }, { "id": "vec3", "sparseValues": { "values": [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094], "indices": [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697] }, "metadata": { "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", "category": "technology", "quarter": "Q3" } }, { "id": "vec4", "sparseValues": { "values": [0.73046875, 0.46972656, 2.84375, 5.2265625, 3.3242188, 1.9863281, 0.9511719, 0.5019531, 4.4257812, 3.4277344, 0.41308594, 4.3242188, 2.4179688, 3.1757812, 1.0224609, 2.0585938, 2.5859375], "indices": [131900689, 152217691, 441495248, 1640781426, 1851149807, 2263326288, 2502307765, 2641553256, 2684780967, 2966813704, 3162218338, 3283104238, 3488055477, 3530642888, 3888762515, 4152503047, 4177290673] }, "metadata": { "chunk_text": "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.", "category": "technology", "quarter": "Q4" } }, ] }' ``` ## Upsert documents Documents are the unit of data in an index with a document schema; see [Document](/guides/get-started/concepts#document) for the definition. Each field in a document is indexed according to the configuration you declared for it in the schema, not just its type — for example, a `string` field can be indexed for BM25 via the `full_text_search` config, and a separate `dense_vector` field can store vector values you provide at upsert time. Indexes with document schemas do not support integrated inference fields such as `semantic_text`. The example below upserts two documents into the `articles` namespace using the document API. Each document is indexed for BM25 ranking on `body`. The `category` field is upserted as metadata — it isn't declared in the schema but is auto-indexed for filtering at upsert time: ```bash theme={null} curl -X POST "https://INDEX_HOST/namespaces/articles/documents/upsert" \ -H "Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-01.alpha" \ -d '{ "documents": [ { "_id": "doc1", "body": "Pinecone serverless indexes scale automatically with your workload.", "category": "platform" }, { "_id": "doc2", "body": "Full-text search uses BM25 ranking on text fields with full-text search enabled.", "category": "search" } ] }' ``` The document API is in public preview and uses the `2026-01.alpha` API version. Indexes with dense or sparse vectors use the stable `2025-10` API version shown in the upsert examples above. Field-name rules: * Fields not declared in the schema are stored on the document, returned via `include_fields`, and automatically indexed for filtering as metadata. The schema declares only ranking fields (FTS-enabled `string`, `dense_vector`, `sparse_vector`). * Field names must be unique, non-empty strings, must not start with `_` (reserved for system-managed fields like `_id` and `_score`) or `$` (reserved for filter operators), and are limited to 64 bytes. Document upsert limits: * Each upsert request can contain up to 1000 documents and must be no larger than 2 MB. * Each document can be no larger than 2 MB. * Each `full_text_search` string field can be no larger than 100 KB and can contain up to 10,000 tokens. * Each token can be no larger than 256 bytes before analyzer truncation. * Metadata fields on a document (everything outside FTS-enabled `string` fields) are limited to 40 KB per document in total. This limit does not apply to `full_text_search` text fields. For the full upsert reference (SDK examples, batching, and the response schema), see [Full-text search](/guides/search/full-text-search). ## Upsert in batches To control costs when ingesting large datasets (10,000,000+ records), use [import](/guides/index-data/import-data) instead of upsert. Send upserts in batches to help increase throughput. * When upserting records with vectors, a batch should be as large as possible (up to 1000 records) without exceeding the [max request size of 2 MB](#upsert-limits). To understand the number of records you can fit into one batch based on the vector dimensions and metadata size, see the following table: | Dimension | Metadata (bytes) | Max batch size | | :-------- | :--------------- | :------------- | | 386 | 0 | 1000 | | 768 | 500 | 559 | | 1536 | 2000 | 245 | * When upserting records with text, a batch can contain up to 96 records. This limit comes from the [hosted embedding models](/guides/index-data/create-an-index#embedding-models) used during integrated embedding rather than the batch size limit for upserting raw vectors. ```Python Python theme={null} import random import itertools from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") def chunks(iterable, batch_size=200): """A helper function to break an iterable into chunks of size batch_size.""" it = iter(iterable) chunk = tuple(itertools.islice(it, batch_size)) while chunk: yield chunk chunk = tuple(itertools.islice(it, batch_size)) vector_dim = 128 vector_count = 10000 # Example generator that generates many (id, vector) pairs example_data_generator = map(lambda i: (f'id-{i}', [random.random() for _ in range(vector_dim)]), range(vector_count)) # Upsert data with 200 vectors per upsert request for ids_vectors_chunk in chunks(example_data_generator, batch_size=200): index.upsert(vectors=ids_vectors_chunk) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from "@pinecone-database/pinecone"; const RECORD_COUNT = 10000; const RECORD_DIMENSION = 128; const client = new Pinecone({ apiKey: "YOUR_API_KEY" }); const index = client.index("docs-example"); // A helper function that breaks an array into chunks of size batchSize const chunks = (array, batchSize = 200) => { const chunks = []; for (let i = 0; i < array.length; i += batchSize) { chunks.push(array.slice(i, i + batchSize)); } return chunks; }; // Example data generation function, creates many (id, vector) pairs const generateExampleData = () => Array.from({ length: RECORD_COUNT }, (_, i) => { return { id: `id-${i}`, values: Array.from({ length: RECORD_DIMENSION }, (_, i) => Math.random()), }; }); const exampleRecordData = generateExampleData(); const recordChunks = chunks(exampleRecordData); // Upsert data with 200 records per upsert request for (const chunk of recordChunks) { await index.upsert({ records: chunk }) } ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.unsigned_indices_model.VectorWithUnsignedIndices; import java.util.Arrays; import java.util.List; public class UpsertBatchExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); ArrayList vectors = generateVectors(); ArrayList> chunks = chunks(vectors, BATCH_SIZE); for (ArrayList chunk : chunks) { index.upsert(chunk, "example-namespace"); } } // A helper function that breaks an ArrayList into chunks of batchSize private static ArrayList> chunks(ArrayList vectors, int batchSize) { ArrayList> chunks = new ArrayList<>(); ArrayList chunk = new ArrayList<>(); for (int i = 0; i < vectors.size(); i++) { if (i % BATCH_SIZE == 0 && i != 0) { chunks.add(chunk); chunk = new ArrayList<>(); } chunk.add(vectors.get(i)); } return chunks; } // Example data generation function, creates many (id, vector) pairs private static ArrayList generateVectors() { Random random = new Random(); ArrayList vectors = new ArrayList<>(); for (int i = 0; i <= RECORD_COUNT; i++) { String id = "id-" + i; ArrayList values = new ArrayList<>(); for (int j = 0; j < RECORD_DIMENSION; j++) { values.add(random.nextFloat()); } VectorWithUnsignedIndices vector = new VectorWithUnsignedIndices(); vector.setId(id); vector.setValues(values); vectors.add(vector); } return vectors; } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } // Generate a large number of vectors to upsert vectorCount := 10000 vectorDim := idx.Dimension vectors := make([]*pinecone.Vector, vectorCount) for i := 0; i < int(vectorCount); i++ { randomFloats := make([]float32, vectorDim) for i := int32(0); i < vectorDim; i++ { randomFloats[i] = rand.Float32() } vectors[i] = &pinecone.Vector{ Id: fmt.Sprintf("doc1#-vector%d", i), Values: randomFloats, } } // Break the vectors into batches of 200 var batches [][]*pinecone.Vector batchSize := 200 for len(vectors) > 0 { batchEnd := batchSize if len(vectors) < batchSize { batchEnd = len(vectors) } batches = append(batches, vectors[:batchEnd]) vectors = vectors[batchEnd:] } // Upsert batches for i, batch := range batches { upsertResp, err := idxConn.UpsertVectors(context.Background(), batch) if err != nil { panic(err) } fmt.Printf("upserted %d vectors (%v of %v batches)\n", upsertResp, i+1, len(batches)) } } ``` ## Upsert in parallel Python SDK v6.0.0 and later provide `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). Asyncio support makes it possible to use Pinecone with modern async web frameworks such as FastAPI, Quart, and Sanic. For more details, see [Async requests](/reference/sdks/python/overview#async-requests). Send multiple upserts in parallel to help increase throughput. Vector operations block until the response has been received. However, they can be made asynchronously as follows: ```Python Python theme={null} # This example uses `async_req=True` and multiple threads. # For a single-threaded approach compatible with modern async web frameworks, # see https://docs.pinecone.io/reference/sdks/python/overview#async-requests import random import itertools from pinecone import Pinecone # Initialize the client with pool_threads=30. This limits simultaneous requests to 30. pc = Pinecone(api_key="YOUR_API_KEY", pool_threads=30) # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") def chunks(iterable, batch_size=200): """A helper function to break an iterable into chunks of size batch_size.""" it = iter(iterable) chunk = tuple(itertools.islice(it, batch_size)) while chunk: yield chunk chunk = tuple(itertools.islice(it, batch_size)) vector_dim = 128 vector_count = 10000 example_data_generator = map(lambda i: (f'id-{i}', [random.random() for _ in range(vector_dim)]), range(vector_count)) # Upsert data with 200 vectors per upsert request asynchronously # - Pass async_req=True to index.upsert() with pc.Index(host="INDEX_HOST", pool_threads=30) as index: # Send requests in parallel async_results = [ index.upsert(vectors=ids_vectors_chunk, async_req=True) for ids_vectors_chunk in chunks(example_data_generator, batch_size=200) ] # Wait for and retrieve responses (this raises in case of error) [async_result.get() for async_result in async_results] ``` ```JavaScript JavaScript theme={null} import { Pinecone } from "@pinecone-database/pinecone"; const RECORD_COUNT = 10000; const RECORD_DIMENSION = 128; const client = new Pinecone({ apiKey: "YOUR_API_KEY" }); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") // A helper function that breaks an array into chunks of size batchSize const chunks = (array, batchSize = 200) => { const chunks = []; for (let i = 0; i < array.length; i += batchSize) { chunks.push(array.slice(i, i + batchSize)); } return chunks; }; // Example data generation function, creates many (id, vector) pairs const generateExampleData = () => Array.from({ length: RECORD_COUNT }, (_, i) => { return { id: `id-${i}`, values: Array.from({ length: RECORD_DIMENSION }, (_, i) => Math.random()), }; }); const exampleRecordData = generateExampleData(); const recordChunks = chunks(exampleRecordData); // Upsert data with 200 records per request asynchronously using Promise.all() await Promise.all(recordChunks.map((chunk) => index.upsert({ records: chunk }))); ``` ```java Java theme={null} import com.google.protobuf.Struct; import com.google.protobuf.Value; import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.proto.UpsertResponse; import io.pinecone.unsigned_indices_model.VectorWithUnsignedIndices; import java.util.ArrayList; import java.util.Arrays; import java.util.concurrent.ExecutorService; import java.util.concurrent.Executors; import java.util.List; public class UpsertExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); // Run 5 threads concurrently and upsert data into pinecone int numberOfThreads = 5; // Create a fixed thread pool ExecutorService executor = Executors.newFixedThreadPool(numberOfThreads); // Submit tasks to the executor for (int i = 0; i < numberOfThreads; i++) { // upsertData int batchNumber = i+1; executor.submit(() -> upsertData(index, batchNumber)); } // Shutdown the executor executor.shutdown(); } private static void upsertData(Index index, int batchNumber) { // Vector ids to be upserted String prefix = "v" + batchNumber; List upsertIds = Arrays.asList(prefix + "_1", prefix + "_2", prefix + "_3"); // List of values to be upserted List> values = new ArrayList<>(); values.add(Arrays.asList(1.0f, 2.0f, 3.0f)); values.add(Arrays.asList(4.0f, 5.0f, 6.0f)); values.add(Arrays.asList(7.0f, 8.0f, 9.0f)); // List of sparse indices to be upserted List> sparseIndices = new ArrayList<>(); sparseIndices.add(Arrays.asList(1L, 2L, 3L)); sparseIndices.add(Arrays.asList(4L, 5L, 6L)); sparseIndices.add(Arrays.asList(7L, 8L, 9L)); // List of sparse values to be upserted List> sparseValues = new ArrayList<>(); sparseValues.add(Arrays.asList(1000f, 2000f, 3000f)); sparseValues.add(Arrays.asList(4000f, 5000f, 6000f)); sparseValues.add(Arrays.asList(7000f, 8000f, 9000f)); List vectors = new ArrayList<>(3); // Metadata to be upserted Struct metadataStruct1 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("action").build()) .putFields("year", Value.newBuilder().setNumberValue(2019).build()) .build(); Struct metadataStruct2 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("thriller").build()) .putFields("year", Value.newBuilder().setNumberValue(2020).build()) .build(); Struct metadataStruct3 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("comedy").build()) .putFields("year", Value.newBuilder().setNumberValue(2021).build()) .build(); List metadataStructList = Arrays.asList(metadataStruct1, metadataStruct2, metadataStruct3); // Upsert data for (int i = 0; i < metadataStructList.size(); i++) { vectors.add(buildUpsertVectorWithUnsignedIndices(upsertIds.get(i), values.get(i), sparseIndices.get(i), sparseValues.get(i), metadataStructList.get(i))); } UpsertResponse upsertResponse = index.upsert(vectors, "example-namespace"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "math/rand" "sync" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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/manage-data/target-an-index idxConn, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } // Generate a large number of vectors to upsert vectorCount := 10000 vectorDim := idx.Dimension vectors := make([]*pinecone.Vector, vectorCount) for i := 0; i < int(vectorCount); i++ { randomFloats := make([]float32, vectorDim) for i := int32(0); i < vectorDim; i++ { randomFloats[i] = rand.Float32() } vectors[i] = &pinecone.Vector{ Id: fmt.Sprintf("doc1#-vector%d", i), Values: randomFloats, } } // Break the vectors into batches of 200 var batches [][]*pinecone.Vector batchSize := 200 for len(vectors) > 0 { batchEnd := batchSize if len(vectors) < batchSize { batchEnd = len(vectors) } batches = append(batches, vectors[:batchEnd]) vectors = vectors[batchEnd:] } // Use channels to manage concurrency and possible errors maxConcurrency := 10 errChan := make(chan error, len(batches)) semaphore := make(chan struct{}, maxConcurrency) var wg sync.WaitGroup for i, batch := range batches { wg.Add(1) semaphore <- struct{}{} go func(batch []*pinecone.Vector, i int) { defer wg.Done() defer func() { <-semaphore }() upsertResp, err := idxConn.UpsertVectors(context.Background(), batch) if err != nil { errChan <- fmt.Errorf("batch %d failed: %v", i, err) return } fmt.Printf("upserted %d vectors (%v of %v batches)\n", upsertResp, i+1, len(batches)) }(batch, i) } wg.Wait() close(errChan) for err := range errChan { if err != nil { fmt.Printf("Error while upserting batch: %v\n", err) } } } ``` ### Python SDK with gRPC Using the Python SDK with gRPC extras can provide higher upsert speeds. Through multiplexing, gRPC is able to handle large amounts of requests in parallel without slowing down the rest of the system (HoL blocking), unlike REST. Moreover, you can pass various retry strategies to the gRPC SDK, including [exponential backoff](/guides/production/error-handling#implement-retry-logic). To install the gRPC version of the SDK: ```Shell Shell theme={null} pip install "pinecone[grpc]" ``` To use the gRPC SDK, import the `pinecone.grpc` subpackage and target an index as usual: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone # This is gRPC client aliased as "Pinecone" pc = Pinecone(api_key='YOUR_API_KEY') # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") ``` To launch multiple read and write requests in parallel, pass `async_req` to the `upsert` operation: ```Python Python theme={null} def chunker(seq, batch_size): return (seq[pos:pos + batch_size] for pos in range(0, len(seq), batch_size)) async_results = [ index.upsert(vectors=chunk, async_req=True) for chunk in chunker(data, batch_size=200) ] # Wait for and retrieve responses (in case of error) [async_result.result() for async_result in async_results] ``` It is possible to get write-throttled faster when upserting using the gRPC SDK. If you see this often, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) while upserting. The syntax for upsert, query, fetch, and delete with the gRPC SDK remain the same as the standard SDK. ## Upsert limits | Metric | Limit | | :----------------------------------------------------------------- | :------------------------------------------------------------ | | Max [batch size](/guides/index-data/upsert-data#upsert-in-batches) | 2 MB or 1000 records with vectors
96 records with text | | Max documents per upsert request | 1000 | | Max document upsert request size | 2 MB | | Max document size | 2 MB | | Max `full_text_search` string fields per schema | 100 | | Max size per `full_text_search` string field | 100 KB | | Max tokens per `full_text_search` string field | 10,000 | | Max bytes per token | 256 bytes | | Max filterable metadata size per document | 40 KB | | Max length for a record ID | 512 characters | | Max dimensionality for dense vectors | 20,000 | | Max non-zero values for sparse vectors | 2048 | | Max dimensionality for sparse vectors | 4.2 billion | The 40 KB filterable metadata limit does not apply to `full_text_search` text fields. # Back up a pod-based index Source: https://docs.pinecone.io/guides/indexes/pods/back-up-a-pod-based-index Legacy guide for backing up Pinecone pod-based indexes using collections. Collections are a pod-only feature not available for serverless indexes. Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates). This page describes how to create a static copy of a pod-based index, also known as a [collection](/guides/indexes/pods/understanding-collections). ## Create a collection To create a backup of your pod-based index, use the [`create_collection`](/reference/api/latest/control-plane/create_collection) operation. The following example creates a [collection](/guides/indexes/pods/understanding-collections) named `example-collection` from an index named `docs-example`: ```python Python theme={null} # pip install "pinecone[grpc]" from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="API_KEY") pc.create_collection("example-collection", "docs-example") ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createCollection({ name: "example-collection", source: "docs-example", }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; public class CreateCollectionExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.createCollection("example-collection", "docs-example"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } collection, err := pc.CreateCollection(ctx, &pinecone.CreateCollectionRequest{ Name: "example-collection", Source: "docs-example", }) if err != nil { log.Fatalf("Failed to create collection: %v", err) } else { fmt.Printf("Successfully created collection: %v", collection.Name) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s POST "https://api.pinecone.io/collections" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "example-collection", "source": "docs-example" }' ``` You can create a collection using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups). ## Check the status of a collection To retrieve the status of the process creating a collection and the size of the collection, use the [`describe_collection`](/reference/api/latest/control-plane/describe_collection) operation. Specify the name of the collection to check. You can only call `describe_collection` on a collection in the current project. The `describe_collection` operation returns an object containing key-value pairs representing the name of the collection, the size in bytes, and the creation status of the collection. The following example gets the creation status and size of a collection named `example-collection`. ```python Python theme={null} # pip install "pinecone[grpc]" from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key='API_KEY') pc.describe_collection(name="example-collection") ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.describeCollection('example-collection'); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.client.model.CollectionModel; public class DescribeCollectionExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); CollectionModel collectionModel = pc.describeCollection("example-collection"); System.out.println(collectionModel); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } collectionName := "example-collection" collection, err := pc.DescribeCollection(ctx, collectionName) if err != nil { log.Fatalf("Error describing collection %v: %v", collectionName, err) } else { fmt.Printf("Collection: %+v", collection) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/collections/example-collection" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` You can check the status of a collection using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups). ## List your collections To get a list of the collections in the current project, use the [`list_collections`](/reference/api/latest/control-plane/list_collections) operation. ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key='API_KEY') pc.list_collections() ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) await pc.listCollections(); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.client.model.CollectionModel; public class ListCollectionsExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); List collectionList = pc.listCollections().getCollections(); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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) } collections, err := pc.ListCollections(ctx) if err != nil { log.Fatalf("Failed to list collections: %v", err) } else { if len(collections) == 0 { fmt.Printf("No collections found in project") } else { for _, collection := range collections { fmt.Printf("collection: %v\n", prettifyStruct(collection)) } } } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/collections" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` You can view a list of your collections using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups). You can view a list of your collections using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups). ## Delete a collection To delete a collection, use the [`delete_collection`](/reference/api/latest/control-plane/delete_collection) operation. Specify the name of the collection to delete. Deleting the collection takes several minutes. During this time, the [`describe_collection`](#check-the-status-of-a-collection) operation returns the status "deleting". ```python Python theme={null} # pip install "pinecone[grpc]" from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key='API_KEY') pc.delete_collection("example-collection") ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) await pc.deleteCollection("example-collection"); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; public class DeleteCollectionExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.deleteCollection("example-collection"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } collectionName := "example-collection" err = pc.DeleteCollection(ctx, collectionName) if err != nil { log.Fatalf("Failed to delete collection: %v\n", err) } else { if len(collections) == 0 { fmt.Printf("No collections found in project") } else { fmt.Printf("Successfully deleted collection \"%v\"\n", collectionName) } } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X DELETE "https://api.pinecone.io/collections/example-collection" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` You can delete a collection using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups). # Choose a pod type and size Source: https://docs.pinecone.io/guides/indexes/pods/choose-a-pod-type-and-size Choose a Pinecone pod type and size (s1, p1, p2). Legacy guide: pods are unavailable to new customers as of August 2025; serverless needs no planning. Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates). When planning your Pinecone deployment, it is important to understand the approximate storage requirements of your vectors to choose the appropriate pod type and number. This page will give guidance on sizing to help you plan accordingly. As with all guidelines, these considerations are general and may not apply to your specific use case. We caution you to always test your deployment and ensure that the index configuration you are using is appropriate to your requirements. [Collections](/guides/indexes/pods/understanding-collections) allow you to create new versions of your index with different pod types and sizes. This also allows you to test different configurations. This guide is merely an overview of sizing considerations; test your index configuration before moving to production. Users on Standard and Enterprise plans can [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) for further help with sizing and testing. ## Overview There are five main considerations when deciding how to configure your Pinecone index: * Number of vectors * Dimensionality of your vectors * Size of metadata on each vector * Queries per second (QPS) throughput * Cardinality of indexed metadata Each of these considerations comes with requirements for index size, pod type, and replication strategy. ### Number of vectors The most important consideration in sizing is the [number of vectors](/guides/index-data/upsert-data) you plan on working with. As a rule of thumb, a single p1 pod can store approximately 1M vectors, while a s1 pod can store 5M vectors. However, this can be affected by other factors, such as dimensionality and metadata, which are explained below. ### Dimensionality of vectors The rules of thumb above for how many vectors can be stored in a given pod assumes a typical configuration of 768 [dimensions per vector](/guides/index-data/create-an-index). As your individual use case will dictate the dimensionality of your vectors, the amount of space required to store them may necessarily be larger or smaller. Each dimension on a single vector consumes 4 bytes of memory and storage per dimension, so if you expect to have 1M vectors with 768 dimensions each, that’s about 3GB of storage without factoring in metadata or other overhead. Using that reference, we can estimate the typical pod size and number needed for a given index. Table 1 below gives some examples of this. **Table 1: Estimated number of pods per 1M vectors by dimensionality** | Pod type | Dimensions | Estimated max vectors per pod | | -------- | ---------: | ----------------------------: | | **p1** | 512 | 1,250,000 | | | 768 | 1,000,000 | | | 1024 | 675,000 | | | 1536 | 500,000 | | **p2** | 512 | 1,250,000 | | | 768 | 1,100,000 | | | 1024 | 1,000,000 | | | 1536 | 550,000 | | **s1** | 512 | 8,000,000 | | | 768 | 5,000,000 | | | 1024 | 4,000,000 | | | 1536 | 2,500,000 | Pinecone does not support fractional pod deployments, so always round up to the next nearest whole number when choosing your pods. ## Queries per second (QPS) QPS speeds are governed by a combination of the [pod type](/guides/indexes/pods/understanding-pod-based-indexes#pod-types) of the index, the number of [replicas](/guides/indexes/pods/scale-pod-based-indexes#add-replicas), and the `top_k` value of queries. The pod type is the primary factor driving QPS, as the different pod types are optimized for different approaches. The [p1 pods](/guides/index-data/indexing-overview/#p1-pods) are performance-optimized pods which provide very low query latencies, but hold fewer vectors per pod than [s1 pods](/guides/index-data/indexing-overview/#s1-pods). They are ideal for applications with low latency requirements (\<100ms). The s1 pods are optimized for storage and provide large storage capacity and lower overall costs with slightly higher query latencies than p1 pods. They are ideal for very large indexes with moderate or relaxed latency requirements. The [p2 pod type](/guides/index-data/indexing-overview/#p2-pods) provides greater query throughput with lower latency. They support 200 QPS per replica and return queries in less than 10ms. This means that query throughput and latency are better than s1 and p1, especially for low dimension vectors (\<512D). As a rule, a single p1 pod with 1M vectors of 768 dimensions each and no replicas can handle about 20 QPS. It’s possible to get greater or lesser speeds, depending on the size of your metadata, number of vectors, the dimensionality of your vectors, and the `top_K` value for your search. See Table 2 below for more examples. **Table 2: QPS by pod type and `top_k` value**\* | Pod type | top\_k 10 | top\_k 250 | top\_k 1000 | | -------- | --------- | ---------- | ----------- | | p1 | 30 | 25 | 20 | | p2 | 150 | 50 | 20 | | s1 | 10 | 10 | 10 | \*The QPS values in Table 2 represent baseline QPS with 1M vectors and 768 dimensions. [Adding replicas](/guides/indexes/pods/scale-pod-based-indexes#add-replicas) is the simplest way to increase your QPS. Each replica increases the throughput potential by roughly the same QPS, so aiming for 150 QPS using p1 pods means using the primary pod and 5 replicas. Using threading or multiprocessing in your application is also important, as issuing single queries sequentially still subjects you to delays from any underlying latency. The [Pinecone gRPC SDK](/guides/index-data/upsert-data#grpc-python-sdk) can also be used to increase throughput of upserts. ### Metadata cardinality and size The last consideration when planning your indexes is the cardinality and size of your [metadata](/guides/index-data/upsert-data#inserting-vectors-with-metadata). While the increases are small when talking about a few million vectors, they can have a real impact as you grow to hundreds of millions or billions of vectors. Indexes with very high cardinality, like those storing a unique user ID on each vector, can have significant memory requirements, resulting in fewer vectors fitting per pod. Also, if the size of the metadata per vector is larger, the index requires more storage. Limiting which metadata fields are indexed using [selective metadata indexing](/guides/indexes/pods/manage-pod-based-indexes#selective-metadata-indexing) can help lower memory usage. ### Pod sizes You can also start with one of the larger [pod sizes](/guides/index-data/indexing-overview/#pod-size-and-performance), like p1.x2. Each step up in pod size doubles the space available for your vectors. We recommend starting with x1 pods and scaling as you grow. This way, you don’t start with too large a pod size and have nowhere else to go up, meaning you have to migrate to a new index before you’re ready. ### Example applications The following examples will showcase how to use the sizing guidelines above to choose the appropriate type, size, and number of pods for your index. #### Example 1: Semantic search of news articles In our first example, we’ll use the demo app for semantic search from our documentation. In this case, we’re only working with 204,135 vectors. The vectors use 300 dimensions each, well under the general measure of 768 dimensions. Using the rule of thumb above of up to 1M vectors per p1 pod, we can run this app comfortably with a single p1.x1 pod. #### Example 2: Facial recognition For this example, suppose you’re building an application to identify customers using facial recognition for a secure banking app. Facial recognition can work with as few as 128 dimensions, but in this case, because the app will be used for access to finances, we want to make sure we’re certain that the person using it is the right one. We plan for 100M customers and use 2048 dimensions per vector. We know from our rules of thumb above that 1M vectors with 768 dimensions fit nicely in a p1.x1 pod. We can just divide those numbers into the new targets to get the ratios we’ll need for our pod estimate: ``` 100M / 1M = 100 base p1 pods 2048 / 768 = 2.667 vector ratio 2.667 * 100 = 267 rounding up ``` So we need 267 p1.x1 pods. We can reduce that by switching to s1 pods instead, sacrificing latency by increasing storage availability. They hold five times the storage of p1.x1, so the math is simple: ``` 267 / 5 = 54 rounding up ``` So we estimate that we need 54 s1.x1 pods to store very high dimensional data for the face of each of the bank’s customers. # Create a pod-based index Source: https://docs.pinecone.io/guides/indexes/pods/create-a-pod-based-index Create a Pinecone pod-based index. Legacy guide: new customers cannot create pod indexes as of August 2025; use serverless index creation instead. Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates). This page shows you how to create a pod-based index. For guidance on serverless indexes, see [Create a serverless index](/guides/index-data/create-an-index). ## Create a pod index To create a pod index, use the [`create_index`](/reference/api/latest/control-plane/create_index) operation as follows: * Provide a `name` for the index. * Specify the `dimension` and `metric` of the vectors you'll store in the index. This should match the dimension and metric supported by your embedding model. * Set `spec.environment` to the [environment](/guides/index-data/create-an-index#cloud-regions) where the index should be deployed. For Python, you also need to import the `ServerlessSpec` class. * Set `spec.pod_type` to the [pod type](/guides/indexes/pods/understanding-pod-based-indexes#pod-types) and [size](/guides/index-data/indexing-overview#pod-size-and-performance) that you want. Other parameters are optional. See the [API reference](/reference/api/latest/control-plane/create_index) for details. ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone, PodSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=PodSpec( environment="us-west1-gcp", pod_type="p1.x1", pods=1 ), deletion_protection="disabled" ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createIndex({ name: 'docs-example', dimension: 1536, metric: 'cosine', spec: { pod: { environment: 'us-west1-gcp', podType: 'p1.x1', pods: 1 } }, deletionProtection: 'disabled', }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.IndexModel; import org.openapitools.db_control.client.model.DeletionProtection; public class CreateIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.createPodsIndex("docs-example", 1536, "us-west1-gcp", "p1.x1", "cosine", DeletionProtection.DISABLED); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } indexName := "docs-example" metric := pinecone.Dotproduct deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreatePodIndex(ctx, &pinecone.CreatePodIndexRequest{ Name: indexName, Metric: &metric, Dimension: 1536, Environment: "us-east1-gcp", PodType: "p1.x1", DeletionProtection: &deletionProtection, }) if err != nil { log.Fatalf("Failed to create pod-based index: %v", idx.Name) } else { fmt.Printf("Successfully created pod-based index: %v", idx.Name) } } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "pod": { "environment": "us-west1-gcp", "pod_type": "p1.x1", "pods": 1 } }, "deletion_protection": "disabled" }' ``` ## Create a pod index from a collection You can create a pod-based index from a collection. For more details, see [Restore an index](/guides/indexes/pods/restore-a-pod-based-index). # Manage pod-based indexes Source: https://docs.pinecone.io/guides/indexes/pods/manage-pod-based-indexes Manage Pinecone pod-based indexes. Legacy guide: pod indexes are unavailable to new customers as of August 2025; serverless is recommended for new projects. Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates). This page shows you how to manage pod-based indexes. For guidance on serverless indexes, see [Manage serverless indexes](/guides/manage-data/manage-indexes). ## Describe a pod-based index Use the [`describe_index`](/reference/api/latest/control-plane/describe_index/) endpoint to get a complete description of a specific index: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.describe_index(name="docs-example") # Response: # {'dimension': 1536, # 'host': 'docs-example-4mkljsz.svc.aped-4627-b74a.pinecone.io', # 'metric': 'cosine', # 'name': 'docs-example', # 'spec': {'pod': {'environment': 'us-east-1-aws', # 'pod_type': 's1.x1', # 'pods': 1, # 'replicas': 1, # 'shards': 1}}, # 'status': {'ready': True, 'state': 'Ready'}} ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.describeIndex('docs-example'); // Response: // { // "name": "docs-example", // "dimension": 1536, // "metric": "cosine", // "host": "docs-example-4mkljsz.svc.aped-4627-b74a.pinecone.io", // "deletionProtection": "disabled", // "spec": { // "pod": { // "environment": "us-east-1-aws", // "pod_type": "s1.x1", // "pods": 1, // "replicas": 1, // "shards": 1 // } // }, // "status": { // "ready": true, // "state": "Ready" // } // } ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class DescribeIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOURE_API_KEY").build(); IndexModel indexModel = pc.describeIndex("docs-example"); System.out.println(indexModel); } } // Response: // class IndexModel { // name: docs-example // dimension: 1536 // metric: cosine // host: docs-example-4mkljsz.svc.aped-4627-b74a.pinecone.io // deletionProtection: disabled // spec: class IndexModelSpec { // serverless: null // pod: class PodSpec { // cloud: aws // region: us-east-1 // environment: us-east-1-aws, // podType: s1.x1, // pods: 1, // replicas: 1, // shards: 1 // } // } // status: class IndexModelStatus { // ready: true // state: Ready // } // } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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) } idx, err := pc.DescribeIndex(ctx, "docs-example") if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err) } else { fmt.Printf("index: %v\n", prettifyStruct(idx)) } } // Response: // index: { // "name": "docs-example", // "dimension": 1536, // "host": "docs-example-4mkljsz.svc.aped-4627-b74a.pinecone.io", // "metric": "cosine", // "deletion_protection": "disabled", // "spec": { // "pod": { // "environment": "us-east-1-aws", // "pod_type": "s1.x1", // "pods": 1, // "replicas": 1, // "shards": 1 // } // }, // "status": { // "ready": true, // "state": "Ready" // } // } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/indexes/docs-example" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" # Response: # { # "name": "docs-example", # "metric": "cosine", # "dimension": 1536, # "status": { # "ready": true, # "state": "Ready" # }, # "host": "docs-example-4mkljsz.svc.aped-4627-b74a.pinecone.io", # "spec": { # "pod": { # "environment": "us-east-1-aws", # "pod_type": "s1.x1", # "pods": 1, # "replicas": 1, # "shards": 1 # } # } # } ``` **Do not target an index by name in production.** When you target an index by name for data operations such as `upsert` and `query`, the SDK gets the unique DNS host for the index using the `describe_index` operation. This is convenient for testing but should be avoided in production because `describe_index` uses a different API than data operations and therefore adds an additional network call and point of failure. Instead, you should get an index host once and cache it for reuse or specify the host directly. ## Delete a pod-based index Use the [`delete_index`](/reference/api/latest/control-plane/delete_index) operation to delete a pod-based index and all of its associated resources. You are billed for a pod-based index even when it is not in use. ```python Python theme={null} # pip install "pinecone[grpc]" from pinecone.grpc import PineconeGRPC as Pinecone, PodSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.delete_index(name="docs-example") ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.deleteIndex('docs-example'); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; public class DeleteIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.deleteIndex("docs-example"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } indexName := "docs-example" err = pc.DeleteIndex(ctx, indexName) if err != nil { log.Fatalf("Failed to delete index: %v", err) } else { fmt.Println("Index \"%v\" deleted successfully", indexName) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X DELETE "https://api.pinecone.io/indexes/docs-example" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` If deletion protection is enabled on an index, requests to delete it will fail and return a `403 - FORBIDDEN` status with the following error: ``` Deletion protection is enabled for this index. Disable deletion protection before retrying. ``` Before you can delete such an index, you must first [disable deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection). You can delete an index using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes). For the index you want to delete, click the three dots to the right of the index name, then click **Delete**. ## Selective metadata indexing For pod-based indexes, Pinecone indexes all metadata fields by default. When metadata fields contains many unique values, pod-based indexes will consume significantly more memory, which can lead to performance issues, pod fullness, and a reduction in the number of possible vectors that fit per pod. To avoid indexing high-cardinality metadata that is not needed for [filtering your queries](/guides/index-data/indexing-overview#metadata) and keep memory utilization low, specify which metadata fields to index using the `metadata_config` parameter. Since high-cardinality metadata does not cause high memory utilization in serverless indexes, selective metadata indexing is not supported. The value for the `metadata_config` parameter is a JSON object containing the names of the metadata fields to index. ```JSON JSON theme={null} { "indexed": [ "metadata-field-1", "metadata-field-2", "metadata-field-n" ] } ``` **Example** The following example creates a pod-based index that only indexes the `genre` metadata field. Queries against this index that filter for the `genre` metadata field may return results; queries that filter for other metadata fields behave as though those fields do not exist. ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone, PodSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=PodSpec( environment="us-west1-gcp", pod_type="p1.x1", pods=1, metadata_config = { "indexed": ["genre"] } ), deletion_protection="disabled" ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createIndex({ name: 'docs-example', dimension: 1536, metric: 'cosine', spec: { pod: { environment: 'us-west1-gcp', podType: 'p1.x1', pods: 1, metadata_config: { indexed: ["genre"] } } }, deletionProtection: 'disabled', }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.IndexModel; import org.openapitools.db_control.client.model.DeletionProtection; public class CreateIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); CreateIndexRequestSpecPodMetadataConfig podSpecMetadataConfig = new CreateIndexRequestSpecPodMetadataConfig(); List indexedItems = Arrays.asList("genre", "year"); podSpecMetadataConfig.setIndexed(indexedItems); pc.createPodsIndex("docs-example", 1536, "us-west1-gcp", "p1.x1", "cosine", podSpecMetadataConfig, DeletionProtection.DISABLED); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } podIndexMetadata := &pinecone.PodSpecMetadataConfig{ Indexed: &[]string{"genre"}, } indexName := "docs-example" metric := pinecone.Dotproduct deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreatePodIndex(ctx, &pinecone.CreatePodIndexRequest{ Name: indexName, Metric: &metric, Dimension: 1536, Environment: "us-east1-gcp", PodType: "p1.x1", DeletionProtection: &deletionProtection, }) if err != nil { log.Fatalf("Failed to create pod-based index: %v", idx.Name) } else { fmt.Printf("Successfully created pod-based index: %v", idx.Name) } } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s https://api.pinecone.io/indexes \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "pod": { "environment": "us-west1-gcp", "pod_type": "p1.x1", "pods": 1, "metadata_config": { "indexed": ["genre"] } } }, "deletion_protection": "disabled" }' ``` ## Prevent index deletion This feature requires [Pinecone API version](/reference/api/versioning) `2024-07`, [Python SDK](/reference/sdks/python/overview) v5.0.0, [Node.js SDK](/reference/sdks/node/overview) v3.0.0, [Java SDK](/reference/sdks/java/overview) v2.0.0, or [Go SDK](/reference/sdks/go/overview) v1.0.0 or later. You can prevent an index and its data from accidental deleting when [creating a new index](/guides/index-data/create-an-index) or when [configuring an existing index](/guides/indexes/pods/manage-pod-based-indexes). In both cases, you set the `deletion_protection` parameter to `enabled`. To enable deletion protection when creating a new index: ```python Python theme={null} # pip install "pinecone[grpc]" from pinecone.grpc import PineconeGRPC as Pinecone, PodSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=PodSpec( environment="us-west1-gcp", pod_type="p1.x1", pods=1 ), deletion_protection="enabled" ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createIndex({ name: 'docs-example', dimension: 1536, metric: 'cosine', spec: { pod: { environment: 'us-west1-gcp', podType: 'p1.x1', pods: 1 } }, deletionProtection: 'enabled', }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.IndexModel; import org.openapitools.db_control.client.model.DeletionProtection; public class CreateIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.createPodsIndex("docs-example", 1536, "us-west1-gcp", "p1.x1", "cosine", DeletionProtection.ENABLED); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } indexName := "docs-example" metric := pinecone.Dotproduct deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreatePodIndex(ctx, &pinecone.CreatePodIndexRequest{ Name: indexName, Metric: &metric, Dimension: 1536, Environment: "us-east1-gcp", PodType: "p1.x1", DeletionProtection: &deletionProtection, }) if err != nil { log.Fatalf("Failed to create pod-based index: %v", idx.Name) } else { fmt.Printf("Successfully created pod-based index: %v", idx.Name) } } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "pod": { "environment": "us-west1-gcp", "pod_type": "p1.x1", "pods": 1 } }, "deletion_protection": "enabled" }' ``` To enable deletion protection when configuring an existing index: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.configure_index( name="docs-example", deletion_protection="enabled" ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const client = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await client.configureIndex('docs-example', { deletionProtection: 'enabled' }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class ConfigureIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.configurePodsIndex("docs-example", DeletionProtection.ENABLED); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } idx, err := pc.ConfigureIndex(ctx, "docs-example", pinecone.ConfigureIndexParams{DeletionProtection: "enabled"}) if err != nil { log.Fatalf("Failed to configure index \"%v\": %v", idx.Name, err) } else { fmt.Printf("Successfully configured index \"%v\"", idx.Name) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "deletion_protection": "enabled" }' ``` When deletion protection is enabled on an index, requests to delete the index fail and return a `403 - FORBIDDEN` status with the following error: ``` Deletion protection is enabled for this index. Disable deletion protection before retrying. ``` ## Disable deletion protection Before you can [delete an index](#delete-a-pod-based-index) with deletion protection enabled, you must first disable deletion protection as follows: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.configure_index( name="docs-example", deletion_protection="disabled" ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const client = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await client.configureIndex('docs-example', { deletionProtection: 'disabled' }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class ConfigureIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.configurePodsIndex("docs-example", DeletionProtection.DISABLED); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } idx, err := pc.ConfigureIndex(ctx, "docs-example", pinecone.ConfigureIndexParams{DeletionProtection: "disabled"}) if err != nil { log.Fatalf("Failed to configure index \"%v\": %v", idx.Name, err) } else { fmt.Printf("Successfully configured index \"%v\"", idx.Name) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "deletion_protection": "disabled" }' ``` ## Delete an entire namespace In pod-based indexes, reads and writes share compute resources, so deleting an entire namespace with many records can increase the latency of read operations. In such cases, consider [deleting records in batches](#delete-records-in-batches). ## Delete records in batches In pod-based indexes, reads and writes share compute resources, so deleting an entire namespace or a large number of records can increase the latency of read operations. To avoid this, delete records in batches of up to 1000, with a brief sleep between requests. Consider using smaller batches if the index has active read traffic. ```python Batch delete a namespace theme={null} from pinecone import Pinecone import numpy as np import time pc = Pinecone(api_key='API_KEY') INDEX_NAME = 'INDEX_NAME' NAMESPACE = 'NAMESPACE_NAME' # Consider using smaller batches if you have a high RPS for read operations BATCH = 1000 index = pc.Index(name=INDEX_NAME) dimensions = index.describe_index_stats()['dimension'] # Create the query vector query_vector = np.random.uniform(-1, 1, size=dimensions).tolist() results = index.query(vector=query_vector, namespace=NAMESPACE, top_k=BATCH) # Delete in batches until the query returns no results while len(results['matches']) > 0: ids = [i['id'] for i in results['matches']] index.delete(ids=ids, namespace=NAMESPACE) time.sleep(0.01) results = index.query(vector=query_vector, namespace=NAMESPACE, top_k=BATCH) ``` ```python Batch delete by metadata theme={null} from pinecone import Pinecone import numpy as np import time pc = Pinecone(api_key='API_KEY') INDEX_NAME = 'INDEX_NAME' NAMESPACE = 'NAMESPACE_NAME' # Consider using smaller batches if you have a high RPS for read operations BATCH = 1000 index = pc.Index(name=INDEX_NAME) dimensions = index.describe_index_stats()['dimension'] METADATA_FILTER = {} # Create the query vector with a filter query_vector = np.random.uniform(-1, 1, size=dimensions).tolist() results = index.query(vector=query_vector, namespace=NAMESPACE, filter=METADATA_FILTER, top_k=BATCH) # Delete in batches until the query returns no results while len(results['matches']) > 0: ids = [i['id'] for i in results['matches']] index.delete(ids=ids, namespace=NAMESPACE) time.sleep(0.01) results = index.query(vector=query_vector, namespace=NAMESPACE, filter=METADATA_FILTER, top_k=BATCH) ``` ## Delete records by metadata In pod-based indexes, if you are targeting a large number of records for deletion and the index has active read traffic, consider [deleting records in batches](#delete-records-in-batches). To delete records from a namespace based on their metadata values, pass a [metadata filter expression](/guides/index-data/indexing-overview#metadata-filter-expressions) to the `delete` operation. This deletes all records in the namespace that match the filter expression. For example, the following code deletes all records with a `genre` field set to `documentary` from namespace `example-namespace`: ```Python Python theme={null} # pip install "pinecone[grpc]" from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.delete( filter={ "genre": {"$eq": "documentary"} }, namespace="example-namespace" ) ``` ```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/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const ns = index.namespace('example-namespace') await ns.deleteMany({ genre: { $eq: "documentary" }, }); ``` ```java Java theme={null} import com.google.protobuf.Struct; import com.google.protobuf.Value; import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import java.util.Arrays; import java.util.List; public class DeleteExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); Struct filter = Struct.newBuilder() .putFields("genre", Value.newBuilder() .setStructValue(Struct.newBuilder() .putFields("$eq", Value.newBuilder() .setStringValue("documentary") .build())) .build()) .build(); index.deleteByFilter(filter, "example-namespace"); } } ``` ```go Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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/manage-data/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) } metadataFilter := map[string]interface{}{ "genre": map[string]interface{}{ "$eq": "documentary", }, } filter, err := structpb.NewStruct(metadataFilter) if err != nil { log.Fatalf("Failed to create metadata filter: %v", err) } err = idxConnection.DeleteVectorsByFilter(ctx, filter) if err != nil { log.Fatalf("Failed to delete vector(s) with filter %+v: %v", filter, err) } } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -i "https://$INDEX_HOST/vectors/delete" \ -H 'Api-Key: $PINECONE_API_KEY' \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "filter": {"genre": {"$eq": "documentary"}}, "namespace": "example-namespace" }' ``` ## Tag an index When configuring an index, you can tag the index to help with index organization and management. For more details, see [Tag an index](/guides/manage-data/manage-indexes#configure-index-tags). ## Manage costs ### Set a project pod limit To control costs, [project owners](/guides/projects/understanding-projects#project-roles) can [set the maximum total number of pods](/reference/api/database-limits#pods-per-project) allowed across all pod-based indexes in a project. The default pod limit is 5. 1. Go to [Settings > Projects](https://app.pinecone.io/organizations/-/settings/projects). 2. For the project you want to update, click the **ellipsis (...) menu > Configure**. 3. In the **Pod Limit** section, update the number of pods. 4. Click **Save Changes**. ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PROJECT_ID="YOUR_PROJECT_ID" curl -X PATCH "https://api.pinecone.io/admin/projects/$PROJECT_ID" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "max_pods": 5 }' ``` The example returns a response like the following: ```json theme={null} { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "example-project", "max_pods": 5, "force_encryption_with_cmek": false, "organization_id": "string", "created_at": "2025-03-17T00:42:31.912Z" } ``` ### Back up inactive pod-based indexes For each pod-based index, billing is determined by the per-minute price per pod and the number of pods the index uses, regardless of index activity. When a pod-based index is not in use, [back it up using collections](/guides/indexes/pods/back-up-a-pod-based-index) and delete the inactive index. When you're ready to use the vectors again, you can [create a new index from the collection](/guides/indexes/pods/create-a-pod-based-index#create-a-pod-index-from-a-collection). This new index can also use a different index type or size. Because it's relatively cheap to store collections, you can reduce costs by only running an index when it's in use. ### Choose the right index type and size Pod sizes are designed for different applications, and some are more expensive than others. [Choose the appropriate pod type and size](/guides/indexes/pods/choose-a-pod-type-and-size), so you pay for the resources you need. For example, the `s1` pod type provides large storage capacity and lower overall costs with slightly higher query latencies than `p1` pods. By switching to a different pod type, you may be able to reduce costs while still getting the performance your application needs. For pod-based indexes, project owners can [set limits for the total number of pods](/reference/api/database-limits#pods-per-project) across all indexes in the project. The default pod limit is 5. ## Monitor performance Pinecone generates time-series performance metrics for each Pinecone index. You can monitor these metrics directly in the Pinecone console or with tools like Prometheus or Datadog. ### Use the Pinecone Console To view performance metrics in the Pinecone console: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select the project containing the index you want to monitor. 3. Go to **Database > Indexes**. 4. Select the index. 5. Go to the **Metrics** tab. ### Use Datadog To monitor Pinecone with Datadog, use Datadog's [Pinecone integration](/integrations/datadog). This feature is available on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). ### Use Prometheus This feature is available on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). When using [Bring Your Own Cloud](/guides/production/bring-your-own-cloud), you must configure Prometheus monitoring within your VPC. To monitor all pod-based indexes in a specific region of a project, insert the following snippet into the [`scrape_configs`](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) section of your `prometheus.yml` file and update it with values for your Prometheus integration: ```YAML theme={null} scrape_configs: - job_name: "pinecone-pod-metrics" scheme: https metrics_path: '/metrics' authorization: credentials: API_KEY static_configs: - targets: ["metrics.ENVIRONMENT.pinecone.io" ] ``` * Replace `API_KEY` with an API key for the project you want to monitor. If necessary, you can [create an new API key](/reference/api/authentication) in the Pinecone console. * Replace `ENVIRONMENT` with the [environment](/guides/indexes/pods/understanding-pod-based-indexes#pod-environments) of the pod-based indexes you want to monitor. For more configuration details, see the [Prometheus docs](https://prometheus.io/docs/prometheus/latest/configuration/configuration/). #### Available metrics The following metrics are available when you integrate Pinecone with Prometheus: | Name | Type | Description | | :----------------------------------- | :-------- | :-------------------------------------------------------------------------------- | | `pinecone_vector_count` | gauge | The number of records per pod in the index. | | `pinecone_request_count_total` | counter | The number of data plane calls made by clients. | | `pinecone_request_error_count_total` | counter | The number of data plane calls made by clients that resulted in errors. | | `pinecone_request_latency_seconds` | histogram | The distribution of server-side processing latency for pinecone data plane calls. | | `pinecone_index_fullness` | gauge | The fullness of the index on a scale of 0 to 1. | #### Metric labels Each metric contains the following labels: | Label | Description | | :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | | `pid` | Process identifier. | | `index_name` | Name of the index to which the metric applies. | | `project_name` | Name of the project containing the index. | | `request_type` | Type of request: `upsert`, `delete`, `fetch`, `query`, or `describe_index_stats`. This label is included only in `pinecone_request_*` metrics. | #### Example queries Return the average latency in seconds for all requests against the Pinecone index `docs-example`: ```shell theme={null} avg by (request_type) (pinecone_request_latency_seconds{index_name="docs-example"}) ``` Return the vector count for the Pinecone index `docs-example`: ```shell theme={null} sum ((avg by (app) (pinecone_vector_count{index_name="docs-example"}))) ``` Return the total number of requests against the Pinecone index `docs-example` over one minute: ```shell theme={null} sum by (request_type)(increase(pinecone_request_count_total{index_name="docs-example"}[60s])) ``` Return the total number of upsert requests against the Pinecone index `docs-example` over one minute: ```shell theme={null} sum by (request_type)(increase(pinecone_request_count_total{index_name="docs-example", request_type="upsert"}[60s])) ``` Return the total errors returned by the Pinecone index `docs-example` over one minute: ```shell theme={null} sum by (request_type) (increase(pinecone_request_error_count{ index_name="docs-example"}[60s])) ``` Return the index fullness metric for the Pinecone index `docs-example`: ``` round(max (pinecone_index_fullness{index_name="docs-example"} * 100)) ``` ## Troubleshooting ### Index fullness errors Serverless indexes automatically scale as needed. However, pod-based indexes can run out of capacity. When that happens, upserting new records will fail with the following error: ```console console theme={null} Index is full, cannot accept data. ``` ### High-cardinality metadata and over-provisioning This [Loom video walkthrough](https://www.loom.com/share/ce6f5dd0c3e14ba0b988fe32d96b703a?sid=48646dfe-c10c-4143-82c6-031fefe05a68) shows you how to manage two scenarios: * The first scenario involves customers loading an index replete with high cardinality metadata. This can trigger a series of unforeseen challenges, and hence, it's vital to comprehend how to manage this situation effectively. This methodology can be applied whenever you need to change your metadata configuration. * The second scenario that we will address involves customers who have over-provisioned the number of pods they need. More specifically, we will discuss the process of re-scaling an index in instances where the customer has previously scaled vertically and now desires to scale the index back down. # Migrate a pod-based index to serverless Source: https://docs.pinecone.io/guides/indexes/pods/migrate-a-pod-based-index-to-serverless Migrate a Pinecone pod-based index to serverless for automatic scaling, better performance, and usage-based pricing with no minimum spend commitment. This page shows you how to migrate a pod-based index to [serverless](/guides/get-started/database-architecture). The migration process is free; the standard costs of upserting records to a new serverless index are not applied. In most cases, migrating to serverless reduces costs significantly. For read-heavy workloads with more than 1 query per second and for indexes with many records in a single namespace, consider building your serverless indexes on [dedicated read nodes](/guides/index-data/dedicated-read-nodes). Before migrating, [contact Pinecone Support](/troubleshooting/contact-support) for help estimating and managing cost implications. ## Limitations Migration is supported for pod-based indexes with less than 25 million records and 20,000 namespaces across all supported clouds (AWS, GCP, and Azure). Also, serverless indexes do not support the following features. If you were using these features for your pod-based index, you will need to adapt your code. If you are blocked by these limitations, [contact Pinecone Support](/troubleshooting/contact-support). * [Selective metadata indexing](/guides/indexes/pods/manage-pod-based-indexes#selective-metadata-indexing) * Because high-cardinality metadata in serverless indexes does not cause high memory utilization, this operation is not relevant. * [Filtering index statistics by metadata](/reference/api/latest/data-plane/describeindexstats) ## How it works Migrating a pod-based index to serverless is a 2-step process: After migration, you will have both a new serverless index and the original pod-based index. Once you've switched your workload to the serverless index, you can delete the pod-based index to avoid paying for unused resources. ## 1. Understand cost implications In most cases, migrating to serverless reduces costs significantly. However, costs can increase for read-heavy workloads with more than 1 query per second and for indexes with many records in a single namespace. Before migrating, consider [contacting Pinecone Support](/troubleshooting/contact-support) for help estimating and managing cost implications. ## 2. Prepare for migration Migrating a pod-based index to serverless can take anywhere from a few minutes to several hours, depending on the size of the index. During that time, you can continue reading from the pod-based index. However, all [upserts](/guides/index-data/upsert-data), [updates](/guides/manage-data/update-data), and [deletes](/guides/manage-data/delete-data) to the pod-based index will not automatically be reflected in the new serverless index, so be sure to prepare in one of the following ways: * **Pause write traffic:** If downtime is acceptable, pause traffic to the pod-based index before starting migration. After migration, you will start sending traffic to the serverless index. * **Log your writes:** If you need to continue reading from the pod-based index during migration, send read traffic to the pod-based index, but log your writes to a temporary location outside of Pinecone (e.g., S3). After migration, you will replay the logged writes to the new serverless index and start sending all traffic to the serverless index. ## 3. Start migration 1. In the [Pinecone console](https://app.pinecone.io/), go to your pod-based index and click the **ellipsis (...) menu > Migrate to serverless**. The dropdown will not display **Migrate to serverless** if the index has any of the listed [limitations](#limitations). 2. To save the legacy index and create a new serverless index now, follow the prompts. Depending on the size of the index, migration can take anywhere from a few minutes to several hours. While migration is in progress, you'll see the yellow **Initializing** status: create index from collection - initializing status When the new serverless index is ready, the status will change to green: create index from collection - ready status 1. Use the [`create_collection`](/reference/api/latest/control-plane/create_collection) operation to create a backup of your pod-based index: ```javascript JavaScript theme={null} // Requires Node.js SDK v6.1.2 or later import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createCollection({ name: "pod-collection", source: "pod-index" }); ``` ```go Go theme={null} // Requires Go SDK v4.1.2 or later package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } collection, err := pc.CreateCollection(ctx, &pinecone.CreateCollectionRequest{ Name: "pod-collection", Source: "pod-index", }) if err != nil { log.Fatalf("Failed to create collection: %v", err) } else { fmt.Printf("Successfully created collection: %v", collection.Name) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s POST "https://api.pinecone.io/collections" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "pod-collection", "source": "pod-index" }' ``` 2. Use the [`create_index`](/reference/api/latest/control-plane/create_index) operation to create a new serverless index from the collection: * Use API verison `2025-04` or later. Creating a serverless index from a collection is not supported in earlier versions. * Set `dimension` to the same dimension as the pod-based index. Changing the dimension is not supported. * Set `cloud` to the cloud where the pod-based index is hosted. Migrating to a different cloud is not supported. * Set `source_collection` to the name of the collection you created in step 1. ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createIndex({ name: 'serverless-index', vectorType: 'dense', dimension: 1536, metric: 'cosine', spec: { serverless: { cloud: 'aws', region: 'us-east-1', sourceCollection: 'pod-collection' } } }); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: "serverless-index", VectorType: "dense", Dimension: 1536, Metric: pinecone.Cosine, Cloud: pinecone.Aws, Region: "us-east-1", SourceCollection: "pod-collection", }) if err != nil { log.Fatalf("Failed to create serverless index: %v", err) } else { fmt.Printf("Successfully created serverless index: %v", idx.Name) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "serverless-index", "vector_type": "dense", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1", "source_collection": "pod-collection" } } }' ``` ## 4. Update SDKs If you are using an older version of the Python, Node.js, Java, or Go SDK, you must update the SDK to work with serverless indexes. 1. Check your SDK version: ```shell Python theme={null} pip show pinecone ``` ```shell JavaScript theme={null} npm list | grep @pinecone-database/pinecone ``` ```shell Java theme={null} # Check your dependency file or classpath ``` ```shell Go theme={null} go list -u -m all | grep go-pinecone ``` 2. If your SDK version is less than 3.0.0 for [Python](https://github.com/pinecone-io/pinecone-python-client), 2.0.0 for [Node.js](https://sdk.pinecone.io/typescript/), 1.0.0 for [Java](https://github.com/pinecone-io/pinecone-java-client), or 1.0.0 for [Go](https://github.com/pinecone-io/go-pinecone), upgrade the SDK as follows: ```Python Python theme={null} pip install "pinecone[grpc]" --upgrade ``` ```JavaScript JavaScript theme={null} npm install @pinecone-database/pinecone@latest ``` ```shell Java theme={null} # Maven io.pinecone pinecone-client 5.0.0 # Gradle implementation "io.pinecone:pinecone-client:5.0.0" ``` ```go Go theme={null} go get -u github.com/pinecone-io/go-pinecone/v4/pinecone@latest ``` ## 5. Adapt existing code You must make some minor code changes to work with serverless indexes. Serverless indexes do not support some features, as outlined in [Limitations](#limitations). If you were relying on these features for your pod-based index, you’ll need to adapt your code. 1. Change how you import the Pinecone library and authenticate and initialize the client: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec, PodSpec # ServerlessSpec and PodSpec are required only when # creating serverless and pod-based indexes. pc = Pinecone(api_key="YOUR_API_KEY") ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class InitializeClientExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); } } ``` ```go Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } } ``` 2. [Listing indexes](/guides/manage-data/manage-indexes) now fetches a complete description of each index. If you were relying on the output of this operation, you'll need to adapt your code. ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index_list = pc.list_indexes() print(index_list) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) const indexList = await pc.listIndexes(); console.log(indexList); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class ListIndexesExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); IndexList indexList = pc.listIndexes(); System.out.println(indexList); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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) } idxs, err := pc.ListIndexes(ctx) if err != nil { log.Fatalf("Failed to list indexes: %v", err) } else { for _, index := range idxs { fmt.Printf("index: %v\n", prettifyStruct(index)) } } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/indexes" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` The `list_indexes` operation now returns a response like the following: ```python Python theme={null} [{ "name": "docs-example-sparse", "metric": "dotproduct", "host": "docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "vector_type": "sparse", "dimension": null, "deletion_protection": "disabled", "tags": { "environment": "development" } }, { "name": "docs-example-dense", "metric": "cosine", "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "vector_type": "dense", "dimension": 1536, "deletion_protection": "disabled", "tags": { "environment": "development" } }] ``` ```javascript JavaScript theme={null} { indexes: [ { name: 'docs-example-sparse', dimension: undefined, metric: 'dotproduct', host: 'docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io', deletionProtection: 'disabled', tags: { environment: 'development', example: 'tag' }, embed: undefined, spec: { pod: undefined, serverless: { cloud: 'aws', region: 'us-east-1' } }, status: { ready: true, state: 'Ready' }, vectorType: 'sparse' }, { name: 'docs-example-dense', dimension: 1536, metric: 'cosine', host: 'docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io', deletionProtection: 'disabled', tags: { environment: 'development', example: 'tag' }, embed: undefined, spec: { pod: undefined, serverless: { cloud: 'aws', region: 'us-east-1' } }, status: { ready: true, state: 'Ready' }, vectorType: 'dense' } ] } ``` ```java Java theme={null} class IndexList { indexes: [class IndexModel { name: docs-example-sparse dimension: null metric: dotproduct host: docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io deletionProtection: disabled tags: {environment=development} embed: null spec: class IndexModelSpec { pod: null serverless: class ServerlessSpec { cloud: aws region: us-east-1 additionalProperties: null } additionalProperties: null } status: class IndexModelStatus { ready: true state: Ready additionalProperties: null } vectorType: sparse additionalProperties: null }, class IndexModel { name: docs-example-dense dimension: 1536 metric: cosine host: docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io deletionProtection: disabled tags: {environment=development} embed: null spec: class IndexModelSpec { pod: null serverless: class ServerlessSpec { cloud: aws region: us-east-1 additionalProperties: null } additionalProperties: null } status: class IndexModelStatus { ready: true state: Ready additionalProperties: null } vectorType: dense additionalProperties: null }] additionalProperties: null } ``` ```go Go theme={null} index: { "name": "docs-example-sparse", "host": "docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io", "metric": "dotproduct", "vector_type": "sparse", "deletion_protection": "disabled", "dimension": null, "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "tags": { "environment": "development" } } index: { "name": "docs-example-dense", "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io", "metric": "cosine", "vector_type": "dense", "deletion_protection": "disabled", "dimension": 1536, "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "tags": { "environment": "development" } } ``` ```json curl theme={null} { "indexes": [ { "name": "docs-example-sparse", "vector_type": "sparse", "metric": "dotproduct", "dimension": null, "status": { "ready": true, "state": "Ready" }, "host": "docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws" } }, "deletion_protection": "disabled", "tags": { "environment": "development" } }, { "name": "docs-example-dense", "vector_type": "dense", "metric": "cosine", "dimension": 1536, "status": { "ready": true, "state": "Ready" }, "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws" } }, "deletion_protection": "disabled", "tags": { "environment": "development" } } ] } ``` 3. [Describing an index](/guides/manage-data/manage-indexes) now returns a description of an index in a different format. It also returns the index host needed to run data plane operations against the index. If you were relying on the output of this operation, you'll need to adapt your code. ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.describe_index(name="docs-example") ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.describeIndex('docs-example'); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class DescribeIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOURE_API_KEY").build(); IndexModel indexModel = pc.describeIndex("docs-example"); System.out.println(indexModel); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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) } idx, err := pc.DescribeIndex(ctx, "docs-example") if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err) } else { fmt.Printf("index: %v\n", prettifyStruct(idx)) } } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/indexes/docs-example" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ## 6. Use your new index When you're ready to cutover to your new serverless index: 1. Your new serverless index has a different name and unique endpoint than your pod-based index. Update your code to target the new serverless index: ```Python Python theme={null} index = pc.Index("YOUR_SERVERLESS_INDEX_NAME") ``` ```JavaScript JavaScript theme={null} const index = pc.index("YOUR_SERVERLESS_INDEX_NAME"); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.clients.Pinecone; public class TargetIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); Index index = pc.getIndexConnection("YOUR_SERVERLESS_INDEX_NAME"); ``` ```go Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } idx, err := pc.DescribeIndex(ctx, "YOUR_SERVERLESS_INDEX_NAME") if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err) } idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: idx.Host, Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host %v: %v", idx.Host, err) } } ``` ```bash curl theme={null} # When using the API directly, you need the unique endpoint for your new serverless index. # See https://docs.pinecone.io/guides/manage-data/target-an-index for details. PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X POST "https://$INDEX_HOST/describe_index_stats" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` 2. Reinitialize your clients. 3. If you logged writes to the pod-based index during migration, replay the logged writes to your serverless index. 4. [Delete the pod-based index](/guides/manage-data/manage-indexes#delete-an-index) to avoid paying for unused resources. It is not possible to save a serverless index as a collection, so if you want to retain the option to recreate your pod-based index, be sure to keep the collection you created earlier. ## See also * [Limits](/reference/api/database-limits) * [Serverless architecture](/guides/get-started/database-architecture) * [Understanding serverless cost](/guides/manage-cost/understanding-cost) # Restore a pod-based index Source: https://docs.pinecone.io/guides/indexes/pods/restore-a-pod-based-index Legacy guide for restoring Pinecone pod-based indexes from collections. Pod indexes are no longer available to new customers as of August 2025. Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates). You can restore a pod-based index by creating a new index from a [collection](/guides/indexes/pods/understanding-collections). ## Create a pod-based index from a collection To create a pod-based index from a [collection](/guides/manage-data/back-up-an-index#pod-based-index-backups-using-collections), use the [`create_index`](/reference/api/latest/control-plane/create_index) endpoint and provide a [`source_collection`](/reference/api/latest/control-plane/create_index#!path=source%5Fcollection\&t=request) parameter containing the name of the collection from which you wish to create an index. The new index can differ from the original source index: the new index can have a different name, number of pods, or pod type. The new index is queryable and writable. ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone, PodSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="docs-example", dimension=128, metric="cosine", spec=PodSpec( environment="us-west-1-gcp", pod_type="p1.x1", pods=1, source_collection="example-collection" ) ) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createIndex({ name: 'docs-example', dimension: 128, metric: 'cosine', spec: { pod: { environment: 'us-west-1-gcp', podType: 'p1.x1', pods: 1, sourceCollection: 'example-collection' } } }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.IndexModel; import org.openapitools.db_control.client.model.DeletionProtection; public class CreateIndexFromCollectionExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.createPodsIndex("docs-example", 1536, "us-west1-gcp", "p1.x1", "cosine", "example-collection", DeletionProtection.DISABLED); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } indexName := "docs-example" metric := pinecone.Dotproduct deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreatePodIndex(ctx, &pinecone.CreatePodIndexRequest{ Name: indexName, Metric: &metric, Dimension: 1536, Environment: "us-east1-gcp", PodType: "p1.x1", SourceCollection: "example-collection", DeletionProtection: &deletionProtection, }) if err != nil { log.Fatalf("Failed to create pod-based index: %v", idx.Name) } else { fmt.Printf("Successfully created pod-based index: %v", idx.Name) } } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 128, "metric": "cosine", "spec": { "pod": { "environment": "us-west-1-gcp", "pod_type": "p1.x1", "pods": 1, "source_collection": "example-collection" } } }' ``` # Scale pod-based indexes Source: https://docs.pinecone.io/guides/indexes/pods/scale-pod-based-indexes Scale Pinecone pod-based indexes by adding pods or replicas. Legacy guide: pod indexes are unavailable to new customers; serverless scales automatically. Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates). While your index can still serve queries, new upserts may fail as the capacity becomes exhausted. If you need to scale your environment to accommodate more vectors, you can modify your existing index and scale it vertically or create a new index and scale horizontally. This page explains how you can scale your [pod-based indexes](/guides/index-data/indexing-overview#pod-based-indexes) horizontally and vertically. ## Vertical vs. horizontal scaling If you need to scale your environment to accommodate more vectors, you can modify your existing index to scale it vertically or create a new index and scale horizontally. This article will describe both methods and how to scale your index effectively. ## Vertical scaling [Vertical scaling](https://www.pinecone.io/learn/testing-p2-collections-scaling/#vertical-scaling-on-p1-and-s1) is fast and involves no downtime. This is a good choice when you can't pause upserts and must continue serving traffic. It also allows you to double your capacity instantly. However, there are some factors to consider. ### Increase pod size The default [pod size](/guides/index-data/indexing-overview#pod-size-and-performance) is `x1`. You can increase the size to `x2`, `x4`, or `x8`. Moving up to the next size effectively doubles the capacity of the index. If you need to scale by smaller increments, then consider horizontal scaling. Increasing the pod size of your index does not result in downtime. Reads and writes continue uninterrupted during the scaling process, which completes in about 10 minutes. You cannot reduce the pod size of your indexes. The number of base pods you specify when you initially create the index is static and cannot be changed. For example, if you start with 10 pods of `p1.x1` and vertically scale to `p1.x2`, this equates to 20 pods worth of usage. Pod types (performance versus storage pods) also cannot be changed with vertical scaling. If you want to change your pod type while scaling, then horizontal scaling is the better option. #### When to increase pod size If your index is at around 90% fullness, we recommend increasing its size. This helps ensure optimal performance and prevents upserts from failing due to capacity constraints. #### How to increase pod size You can increase the pod size in the Pinecone console or using the API. 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select the project containing the index you want to configure. 3. Go to **Database > Indexes**. 4. Select the index. 5. Click the **...** button. 6. Select **Configure**. 7. In the dropdown, choose the pod size to use. 8. Click **Confirm**. Use the [`configure_index`](/reference/api/latest/control-plane/configure_index) operation and append the new size to the `pod_type` parameter, separated by a period (.). **Example** The following example assumes that `docs-example` has size `x1` and increases the size to `x2`. ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.configure_index("docs-example", pod_type="s1.x2") ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pinecone = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.configureIndex('docs-example', { spec: { pod: { podType: 's1.x2', }, }, }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; public class ConfigureIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("PINECONE_API_KEY").build(); pc.configurePodsIndex("docs-example", "s1.x2"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } idx, err := pc.ConfigureIndex(ctx, "docs-example", pinecone.ConfigureIndexParams{PodType: "s1.x2"}) if err != nil { log.Fatalf("Failed to configure index \"%v\": %v", idx.Name, err) } else { fmt.Printf("Successfully configured index \"%v\"", idx.Name) } } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example-curl" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "pod_type": "s1.x2" }' ``` The size change can take up to 15 minutes to complete. ### Decrease pod size After creating an index, you cannot vertically downscale the index/pod size. Instead, you must [create a collection](/guides/indexes/pods/back-up-a-pod-based-index) and then [create a new index from your collection](/guides/indexes/pods/restore-a-pod-based-index) and specify your desired pod size. ### Check the status of a pod size change To check the status of a pod size change, use the [`describe_index`](/reference/api/latest/control-plane/describe_index/) endpoint. The `status` field in the results contains the key-value pair `"state":"ScalingUp"` or `"state":"ScalingDown"` during the resizing process and the key-value pair `"state":"Ready"` after the process is complete. The index fullness metric provided by [`describe_index_stats`](/reference/api/latest/data-plane/describeindexstats) may be inaccurate until the resizing process is complete. **Example** The following example uses `describe_index` to get the index status of the index `docs-example`. The `status` field contains the key-value pair `"state":"ScalingUp"`, indicating that the resizing process is still ongoing. ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.describe_index(name="docs-example") ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.describeIndex({ name: "docs-example", }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class DescribeIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); IndexModel indexModel = pc.describeIndex("docs-example"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } idx, err := pc.DescribeIndex(ctx, "docs-example") if err != nil { log.Fatalf("Failed to describe index %v: %v", idx.Name, err) } else { fmt.Printf("Successfully found index: %v", idx.Name) } } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s -X GET "https://api.pinecone.io/indexes/docs-example-curl" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ## Horizontal scaling There are two approaches to horizontal scaling in Pinecone: adding pods and adding replicas. Adding pods increases all resources but requires a pause in upserts; adding replicas only increases throughput and requires no pause in upserts. ### Add pods Adding additional pods to a running index is not supported directly. However, you can increase the number of pods by using our [collections](/guides/indexes/pods/understanding-collections) feature to create a new index with more pods. A collection is an immutable snapshot of your index in time: a collection stores the data but not the original index configuration. When you [create an index from a collection](/guides/indexes/pods/create-a-pod-based-index#create-a-pod-index-from-a-collection), you define the new index configuration. This allows you to scale the base pod count horizontally without scaling vertically. The main advantage of this approach is that you can scale incrementally instead of doubling capacity as with vertical scaling. Also, you can redefine pod types if you are experimenting or if you need to use a different pod type, such as performance-optimized pods or storage-optimized pods. Another advantage of this method is that you can change your [metadata configuration](/guides/indexes/pods/manage-pod-based-indexes#selective-metadata-indexing) to redefine metadata fields as indexed or stored-only. This is important when tuning your index for the best throughput. Here are the general steps to make a copy of your index and create a new index while changing the pod type, pod count, metadata configuration, replicas, and all typical parameters when creating a new collection: 1. Pause upserts. 2. Create a collection from the current index. 3. Create an index from the collection with new parameters. 4. Continue upserts to the newly created index. Note: the URL has likely changed. 5. Delete the old index if desired. For detailed steps on creating the collection, see [backup indexes](/guides/manage-data/back-up-an-index#create-a-backup-using-a-collection). For steps on creating an index from a collection, see [Create an index from a collection](/guides/indexes/pods/create-a-pod-based-index#create-a-pod-index-from-a-collection). ### Add replicas Each replica duplicates the resources and data in an index. This means that adding additional replicas increases the throughput of the index but not its capacity. However, adding replicas does not require downtime. Throughput in terms of queries per second (QPS) scales linearly with the number of replicas per index. #### When to add replicas There are two primary scenarios where adding replicas is beneficial: **Increase QPS**: The primary reason to add replicas is to increase your index's queries per second (QPS). Each new replica adds another pod for reading from your index and, generally speaking, will increase your QPS by an equal amount as a single pod. For example, if you consistently get 25 QPS for a single pod, each replica will result in 25 more QPS. If you don't see an increase in QPS after adding replicas, add multiprocessing to your application to ensure you are running parallel operations. You can use the [Pinecone gRPC SDK](/guides/index-data/upsert-data#grpc-python-sdk), or your multiprocessing library of choice. **Provide data redundancy**: When you add a replica to your index, the Pinecone controller will choose a zone in the same region that does not currently have a replica, up to a maximum of three zones (your fourth and subsequent replicas will be hosted in zones with existing replicas). If your application requires multizone redundancy, this is our recommended approach to achieve that. #### How to add replicas To add replicas, use the `configure_index` endpoint to increase the number of replicas for your index: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.configure_index("docs-example", replicas=4) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.configureIndex('docs-example', { spec: { pod: { replicas: 4, }, }, }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; public class ConfigureIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("PINECONE_API_KEY").build(); pc.configurePodsIndex("docs-example", 4, DeletionProtection.DISABLED); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } idx, err := pc.ConfigureIndex(ctx, "docs-example", pinecone.ConfigureIndexParams{Replicas: 4}) if err != nil { log.Fatalf("Failed to configure index \"%v\": %v", idx.Name, err) } else { fmt.Printf("Successfully configured index \"%v\"", idx.Name) } } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example-curl" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "replicas": 4 }' ``` ## Next steps * See our learning center for more information on [vertical scaling](https://www.pinecone.io/learn/testing-p2-collections-scaling/#vertical-scaling-on-p1-and-s1). * Learn more about [collections](/guides/indexes/pods/understanding-collections). # Understanding collections Source: https://docs.pinecone.io/guides/indexes/pods/understanding-collections Legacy documentation for Pinecone collections, a pod-only feature for creating static index snapshots. Collections are not available for serverless indexes. Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates). A collection is a static copy of a pod-based index that only consumes storage. It is a non-queryable representation of a set of records. You can [create a collection](/guides/indexes/pods/back-up-a-pod-based-index) of a pod-based index, and you can [create a new pod-based index from a collection](/guides/manage-data/restore-an-index). This allows you to restore the index with the same or different configurations. Once a collection is created, it cannot be moved to a different project. ## Use cases Creating a collection is useful when performing tasks like the following: * Protecting an index from manual or system failures. * Temporarily shutting down an index. * Copying the data from one index into a different index. * Making a backup of your index. * Experimenting with different index configurations. ## Performance Collections operations perform differently, depending on the pod type of the index: * Creating a `p1` or `s1` index from a collection takes approximately 10 minutes. * Creating a `p2` index from a collection can take several hours when the number of vectors is on the order of 1,000,000. ## Limitations Collection limitations are as follows: * You can only perform operations on collections in the current Pinecone project. ## Pricing See [Pricing](https://www.pinecone.io/pricing/) for up-to-date pricing information. # Understanding pod-based indexes Source: https://docs.pinecone.io/guides/indexes/pods/understanding-pod-based-indexes Understand Pinecone pod-based indexes, including pod types and sizing. Legacy: pod indexes are unavailable to new customers; use serverless for new projects. Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates). With pod-based indexes, you choose one or more pre-configured units of hardware (pods). Depending on the pod type, pod size, and number of pods used, you get different amounts of storage and higher or lower latency and throughput. Be sure to [choose an appropriate pod type and size](/guides/indexes/pods/choose-a-pod-type-and-size) for your dataset and workload. ## Pod types Different pod types are priced differently. See [Understanding cost](/guides/manage-cost/understanding-cost) for more details. Once a pod-based index is created, you cannot change its pod type. However, you can create a collection from an index and then [create a new index with a different pod type](/guides/indexes/pods/create-a-pod-based-index#create-a-pod-index-from-a-collection) from the collection. ### s1 pods These storage-optimized pods provide large storage capacity and lower overall costs with slightly higher query latencies than p1 pods. They are ideal for very large indexes with moderate or relaxed latency requirements. Each s1 pod has enough capacity for around 5M vectors of 768 dimensions. ### p1 pods These performance-optimized pods provide very low query latencies, but hold fewer vectors per pod than s1 pods. They are ideal for applications with low latency requirements (\<100ms). Each p1 pod has enough capacity for around 1M vectors of 768 dimensions. ### p2 pods The p2 pod type provides greater query throughput with lower latency. For vectors with fewer than 128 dimension and queries where `topK` is less than 50, p2 pods support up to 200 QPS per replica and return queries in less than 10ms. This means that query throughput and latency are better than s1 and p1. Each p2 pod has enough capacity for around 1M vectors of 768 dimensions. However, capacity may vary with dimensionality. The data ingestion rate for p2 pods is significantly slower than for p1 pods; this rate decreases as the number of dimensions increases. For example, a p2 pod containing vectors with 128 dimensions can upsert up to 300 updates per second; a p2 pod containing vectors with 768 dimensions or more supports upsert of 50 updates per second. Because query latency and throughput for p2 pods vary from p1 pods, test p2 pod performance with your dataset. The p2 pod type does not support sparse vector values. ## Pod size and performance Each pod type supports four pod sizes: `x1`, `x2`, `x4`, and `x8`. Your index storage and compute capacity doubles for each size step. The default pod size is `x1`. You can increase the size of a pod after index creation. To learn about changing the pod size of an index, see [Configure an index](/guides/indexes/pods/scale-pod-based-indexes#increase-pod-size). ## Pod environments When creating a pod-based index, you must choose the cloud environment where you want the index to be hosted. The project environment can affect your [pricing](https://pinecone.io/pricing). The following table lists the available cloud regions and the corresponding values of the `environment` parameter for the [`create_index`](/guides/index-data/create-an-index#create-a-pod-based-index) endpoint: | Cloud | Region | Environment | | ----- | ---------------------------- | ----------------------------- | | GCP | us-west-1 (N. California) | `us-west1-gcp` | | GCP | us-central-1 (Iowa) | `us-central1-gcp` | | GCP | us-west-4 (Las Vegas) | `us-west4-gcp` | | GCP | us-east-4 (Virginia) | `us-east4-gcp` | | GCP | northamerica-northeast-1 | `northamerica-northeast1-gcp` | | GCP | asia-northeast-1 (Japan) | `asia-northeast1-gcp` | | GCP | asia-southeast-1 (Singapore) | `asia-southeast1-gcp` | | GCP | us-east-1 (South Carolina) | `us-east1-gcp` | | GCP | eu-west-1 (Belgium) | `eu-west1-gcp` | | GCP | eu-west-4 (Netherlands) | `eu-west4-gcp` | | AWS | us-east-1 (Virginia) | `us-east-1-aws` | | Azure | eastus (Virginia) | `eastus-azure` | [Contact us](http://www.pinecone.io/contact/) if you need a dedicated deployment in other regions. The environment cannot be changed after the index is created. ## Pod costs For each pod-based index, billing is determined by the per-minute price per pod and the number of pods the index uses, regardless of index activity. The per-minute price varies by pod type, pod size, account plan, and cloud region. For the latest pod-based index pricing rates, see [Pricing](https://www.pinecone.io/pricing/pods). Total cost depends on a combination of factors: * **Pod type.** Each pod type has different per-minute pricing. * **Number of pods.** This includes replicas, which duplicate pods. * **Pod size.** Larger pod sizes have proportionally higher costs per minute. * **Total pod-minutes.** This includes the total time each pod is running, starting at pod creation and rounded up to 15-minute increments. * **Cloud provider.** The cost per pod-type and pod-minute varies depending on the cloud provider you choose for your project. * **Collection storage.** Collections incur costs per GB of data per minute in storage, rounded up to 15-minute increments. * **Plan.** The free plan incurs no costs; the Standard or Enterprise plans incur different costs per pod-type, pod-minute, cloud provider, and collection storage. The following equation calculates the total costs accrued over time: ``` (Number of pods) * (pod size) * (number of replicas) * (minutes pod exists) * (pod price per minute) + (collection storage in GB) * (collection storage time in minutes) * (collection storage price per GB per minute) ``` To see a calculation of your current usage and costs, go to [**Settings > Usage**](https://app.pinecone.io/organizations/-/settings/usage) in the Pinecone console. While our pricing page lists rates on an hourly basis for ease of comparison, this example lists prices per minute, as this is how Pinecone calculates billing. An example application has the following requirements: * 1,000,000 vectors with 1536 dimensions * 150 queries per second with `top_k` = 10 * Deployment in an EU region * Ability to store 1GB of inactive vectors [Based on these requirements](/guides/indexes/pods/choose-a-pod-type-and-size), the organization chooses to configure the project to use the Standard billing plan to host one `p1.x2` pod with three replicas and a collection containing 1 GB of data. This project runs continuously for the month of January on the Standard plan. The components of the total cost for this example are given in Table 1 below: **Table 1: Example billing components** | Billing component | Value | | ----------------------------- | ------------ | | Number of pods | 1 | | Number of replicas | 3 | | Pod size | x2 | | Total pod count | 6 | | Minutes in January | 44,640 | | Pod-minutes (pods \* minutes) | 267,840 | | Pod price per minute | \$0.0012 | | Collection storage | 1 GB | | Collection storage minutes | 44,640 | | Price per storage minute | \$0.00000056 | The invoice for this example is given in Table 2 below: **Table 2: Example invoice** | Product | Quantity | Price per unit | Charge | | ------------- | -------- | -------------- | -------- | | Collections | 44,640 | \$0.00000056 | \$0.025 | | P2 Pods (AWS) | 0 | | \$0.00 | | P2 Pods (GCP) | 0 | | \$0.00 | | S1 Pods | 0 | | \$0.00 | | P1 Pods | 267,840 | \$0.0012 | \$514.29 | Amount due \$514.54 ## Known limitations * [Pod storage capacity](#pod-types) * Each **p1** pod has enough capacity for 1M vectors with 768 dimensions. * Each **s1** pod has enough capacity for 5M vectors with 768 dimensions. * [Metadata](/guides/index-data/indexing-overview#metadata) * Metadata with high cardinality, such as a unique value for every vector in a large index, uses more memory than expected and can cause the pods to become full. * [Collections](/guides/manage-data/back-up-an-index#pod-based-index-backups-using-collections) * You cannot query or write to a collection after its creation. For this reason, a collection only incurs storage costs. * You can only perform operations on collections in the current Pinecone project. * [Sparse-dense vectors](/guides/search/hybrid-search#use-a-single-index-for-dense-and-sparse-vectors) * Only `s1` and `p1` [pod-based indexes](/guides/indexes/pods/understanding-pod-based-indexes#pod-types) using the dotproduct distance metric support sparse-dense vectors. # Manage cost Source: https://docs.pinecone.io/guides/manage-cost/manage-cost Reduce Pinecone spend with strategies like spend alerts, ID-prefix listing, multitenant namespaces, prepaid credits, and support cost optimization help. For the latest pricing details, see our [pricing page](https://www.pinecone.io/pricing/). For help estimating total cost, see [Understanding cost](/guides/manage-cost/understanding-cost). To view or download a detailed report of your current usage and costs, see [Monitor usage and costs](/guides/manage-cost/monitor-usage-and-costs#monitor-organization-level-usage). To lower your bill, see [Ways to reduce cost](/guides/manage-cost/understanding-cost#ways-to-reduce-cost) and [Save on costs](/guides/optimize/save-on-costs), which cover available credits and discounts plus ways to optimize your workload. ## Set monthly spend alerts You can set up email alerts to monitor your organization's monthly spending. These alerts notify designated recipients when spending reaches specified thresholds. The alerts automatically reset at the start of each monthly billing cycle. Spend alerts are available on the [Standard and Enterprise plans](https://www.pinecone.io/pricing/). They are not needed on the Starter or Builder plans, where usage is capped by plan quotas rather than billed per unit. To set a spend alert: 1. Go to [Settings > Spend alerts](https://app.pinecone.io/organizations/-/settings/spend-alerts) in the Pinecone console 2. Click **+ Add Alert**. 3. Enter the dollar amount for the spend alert. 4. Enter the email addresses to send the alert to. [Organization owners](/guides/organizations/understanding-organizations#organization-roles) are listed by default. 5. Click **Create**. To edit a spend alert: 1. In the row of the spend alert you want to edit, click **ellipsis (...) menu > Edit**. 2. Change the dollar amount and/or email addresses for the spend alert. 3. Click **Update**. **Auto-spend spike alert**: To protect from unexpected cost increases, Pinecone sends an alert when spending exceeds double your previous month's invoice amount. While the alert threshold is fixed and the alert cannot be deleted, you can modify which email addresses receive the alert and enable or disable the alert notifications. ## List by ID prefix By using a [hierarchical ID schema](/guides/index-data/data-modeling#use-structured-ids), you can retrieve records without performing a query. To do so, you can use [`list`](/reference/api/latest/data-plane/list) to retrieve records by ID prefix, then use `fetch` to retrieve the records you need. This can reduce costs, because [`query` consumes more RUs when scanning a larger namespace](/guides/manage-cost/understanding-cost#query), while [`fetch` consumes a fixed ratio of RUs to records retrieved](/guides/manage-cost/understanding-cost#fetch). ## Use namespaces for multitenancy If your application requires you to isolate the data of each customer/user, consider [implementing multitenancy with serverless indexes and namespaces](/guides/index-data/implement-multitenancy). With serverless indexes, you pay only for the amount of data stored and operations performed. For queries in particular, the cost is partly based on the total number of records that must be scanned, so using namespaces can significantly reduce query costs. ## Prepaid credits Pinecone offers an incentive for customers who purchase prepaid credits with an upfront payment. Customers may purchase between \$8,000 and \$25,000 in prepaid credits. Customers who purchase prepaid credits can unlock additional usage capacity at no extra cost. The available benefits vary based on the selected plan and prepaid amount. Prepaid credits apply to Pinecone services at List Price. Any usage that exceeds the available prepaid credits will be billed at full List Price. Customers on Standard and Enterprise pay-as-you-go plans can purchase prepaid credits directly by navigating in the Pinecone console to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans). Purchasing prepaid credits is not available through cloud marketplace billing. To purchase prepaid credits through a cloud marketplace, contact [ar@pinecone.io](mailto:ar@pinecone.io). ## Talk to support Users on Standard and Enterprise plans can [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) for help in optimizing costs. ## See also * [Understanding cost](/guides/manage-cost/understanding-cost) * [Monitor usage and costs](/guides/manage-cost/monitor-usage-and-costs) * [Save on costs](/guides/optimize/save-on-costs) # Monitor usage and costs Source: https://docs.pinecone.io/guides/manage-cost/monitor-usage-and-costs Monitor Pinecone usage and costs at the organization, index, and operation level by tracking read units, write units, and storage consumption. ## Monitor organization-level usage and costs To view usage and costs across your Pinecone organization, you must be an [organization owner or billing admin](/guides/organizations/understanding-organizations#organization-roles). Also, this feature is available only to organizations on the Standard or Enterprise plans. The **Usage** dashboard in the Pinecone console gives you a detailed report of usage and costs across your organization, broken down by each billable SKU or aggregated by project or service. You can view the report in the console or download it as a CSV file for more detailed analysis. 1. Go to [**Settings > Usage**](https://app.pinecone.io/organizations/-/settings/usage) in the Pinecone console. 2. Select the time range to report on. This defaults to the last 30 days. 3. Select the scope for your report: * **SKU:** The usage and cost for each billable SKU, for example, read units per cloud region, storage size per cloud region, or tokens per embedding model. * **Project:** The aggregated cost for each project in your organization. * **Service:** The aggregated cost for each service your organization uses, for example, database (includes serverless back up and restore), assistants, inference (embedding and reranking), and collections. 4. Choose the specific SKUs, projects, or services you want to report on. This defaults to all. 5. To download the report as a CSV file, click **Download**. The CSV download provides more granular detail than the console view, including breakdowns by individual index as well as project and index tags. Dates are shown in UTC to match billing invoices. Cost data is delayed up to three days from the actual usage date. ## Monitor index-level usage You can monitor index-level usage directly in the Pinecone console, or you can pull them into [Prometheus](https://prometheus.io/). For more details, see [Monitoring](/guides/production/monitoring). ## Monitor operation-level usage ### Read units [Query](/guides/search/search-overview), [fetch](/guides/manage-data/fetch-data), and [list by ID](/guides/manage-data/list-record-ids) requests return a `usage` parameter with the [read unit](/guides/manage-cost/understanding-cost#read-units) consumption of each request that is made. While Pinecone tracks read unit usage with decimal precision, the Pinecone API and SDKs round these values up to the nearest whole number in query, fetch, and list responses. For example, if a query uses 0.45 read units, the API and SDKs will report it as 1 read unit. For precise read unit reporting, see [index-level metrics](/guides/production/monitoring) or the organization-wide [Usage dashboard](/guides/manage-cost/monitor-usage-and-costs#monitor-organization-level-usage-and-costs). Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. Example query request: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index("example-index") response = index.query( vector=[0.22,0.43,0.16,1,...], namespace='example-namespace', top_k=3, include_values=False, include_metadata=False ) print(response) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }) const index = pc.index("example-index") const queryResponse = await index.namespace('example-namespace').query({ vector: [0.22,0.43,0.16,1,...], topK: 3, includeValues: false, includeMetadata: false, }); console.log(queryResponse); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices; import java.util.Arrays; import java.util.List; public class QueryByVector { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "example-index"); List query = Arrays.asList(0.22f,0.43f,0.16f,1f,...); QueryResponseWithUnsignedIndices queryResponse = index.query(3, query, null, null, null, "example-namespace", null, false, false); System.out.println(queryResponse); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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/manage-data/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) } queryVector := []float32{0.22, 0.43, 0.16, 1, ...} res, err := idxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{ Vector: queryVector, TopK: 3, IncludeValues: false, }) if err != nil { log.Fatalf("Error encountered when querying by vector: %v", err) } else { fmt.Printf(prettifyStruct(res)) } ``` The response looks like this: ```python Python theme={null} {'matches': [{'id': 'record_193027', 'score': 0.00405937387, 'values': []}, {'id': 'record_137452', 'score': 0.00405937387, 'values': []}, {'id': 'record_132264', 'score': 0.00405937387, 'values': []}], 'namespace': 'example-namespace', 'usage': {'read_units': 1}} ``` ```javascript JavaScript theme={null} { matches: [ { id: 'record_186225', score: 0.00405937387, values: [], sparseValues: undefined, metadata: undefined }, { id: 'record_164994', score: 0.00405937387, values: [], sparseValues: undefined, metadata: undefined }, { id: 'record_186333', score: 0.00405937387, values: [], sparseValues: undefined, metadata: undefined } ], namespace: 'example-namespace', usage: { readUnits: 1 } } ``` ```java Java theme={null} class QueryResponseWithUnsignedIndices { matches: [ScoredVectorWithUnsignedIndices { score: 0.004059374 id: record_170370 values: [] metadata: sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices { indicesWithUnsigned32Int: [] values: [] } }, ScoredVectorWithUnsignedIndices { score: 0.004059374 id: record_107423 values: [] metadata: sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices { indicesWithUnsigned32Int: [] values: [] } }, ScoredVectorWithUnsignedIndices { score: 0.004059374 id: record_171426 values: [] metadata: sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices { indicesWithUnsigned32Int: [] values: [] } }] namespace: example-index usage: read_units: 1 } ``` ```go Go theme={null} { "matches": [ { "vector": { "id": "record_193027" }, "score": 0.004059374 }, { "vector": { "id": "record_137452" }, "score": 0.004059374 }, { "vector": { "id": "record_132264" }, "score": 0.004059374 } ], "usage": { "read_units": 1 }, "namespace": "example-index" } ``` For a more in-depth demonstration of how to use read units to inspect read costs, see [this notebook](https://github.com/pinecone-io/examples/blob/master/docs/read-units-demonstrated.ipynb). ### Egress [Query](/guides/search/search-overview), [fetch](/guides/manage-data/fetch-data), [list](/guides/manage-data/list-record-ids), and [text search](/reference/api/latest/data-plane/search_records) requests return the [egress](/guides/manage-cost/understanding-cost#egress) consumed by each request in the `usage` object, as `egressBytes` (the total bytes returned by the operation, including IDs, scores, values, and metadata). Egress is reported only on serverless reads that return record data. It is omitted on empty results and on requests that return no record data (such as index statistics and management requests). ### Embedding tokens Requests to one of [Pinecone's hosted embedding models](/guides/index-data/create-an-index#embedding-models), either directly via the [`embed` operation](/reference/api/latest/inference/generate-embeddings) or automatically when upserting or querying an [index with integrated embedding](/guides/index-data/indexing-overview#integrated-embedding), return a `usage` parameter with the total tokens generated. For example, the following request to use the `multilingual-e5-large` model to generate embeddings for sentences related to the word “apple” might return this request and summary of embedding tokens generated: ```python Python theme={null} # Import the Pinecone library from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec import time # Initialize a Pinecone client with your API key pc = Pinecone(api_key="YOUR_API_KEY") # Define a sample dataset where each item has a unique ID and piece of text data = [ {"id": "vec1", "text": "Apple is a popular fruit known for its sweetness and crisp texture."}, {"id": "vec2", "text": "The tech company Apple is known for its innovative products like the iPhone."}, {"id": "vec3", "text": "Many people enjoy eating apples as a healthy snack."}, {"id": "vec4", "text": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."}, {"id": "vec5", "text": "An apple a day keeps the doctor away, as the saying goes."}, {"id": "vec6", "text": "Apple Computer Company was founded on April 1, 1976, by Steve Jobs, Steve Wozniak, and Ronald Wayne as a partnership."} ] # Convert the text into numerical vectors that Pinecone can index embeddings = pc.inference.embed( model="llama-text-embed-v2", inputs=[d['text'] for d in data], parameters={"input_type": "passage", "truncate": "END"} ) print(embeddings) ``` ```javascript JavaScript theme={null} // Import the Pinecone library import { Pinecone } from '@pinecone-database/pinecone'; // Initialize a Pinecone client with your API key const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); // Define a sample dataset where each item has a unique ID and piece of text const data = [ { id: 'vec1', text: 'Apple is a popular fruit known for its sweetness and crisp texture.' }, { id: 'vec2', text: 'The tech company Apple is known for its innovative products like the iPhone.' }, { id: 'vec3', text: 'Many people enjoy eating apples as a healthy snack.' }, { id: 'vec4', text: 'Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces.' }, { id: 'vec5', text: 'An apple a day keeps the doctor away, as the saying goes.' }, { id: 'vec6', text: 'Apple Computer Company was founded on April 1, 1976, by Steve Jobs, Steve Wozniak, and Ronald Wayne as a partnership.' } ]; // Convert the text into numerical vectors that Pinecone can index const model = 'llama-text-embed-v2'; const embeddings = await pc.inference.embed( model, data.map(d => d.text), { inputType: 'passage', truncate: 'END' } ); console.log(embeddings); ``` ```java Java theme={null} // Import the required classes import io.pinecone.clients.Index; import io.pinecone.clients.Inference; import io.pinecone.clients.Pinecone; import org.openapitools.inference.client.ApiException; import org.openapitools.inference.client.model.Embedding; import org.openapitools.inference.client.model.EmbeddingsList; import java.math.BigDecimal; import java.util.*; import java.util.stream.Collectors; public class GenerateEmbeddings { public static void main(String[] args) throws ApiException { // Initialize a Pinecone client with your API key Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); Inference inference = pc.getInferenceClient(); // Prepare input sentences to be embedded List data = Arrays.asList( new DataObject("vec1", "Apple is a popular fruit known for its sweetness and crisp texture."), new DataObject("vec2", "The tech company Apple is known for its innovative products like the iPhone."), new DataObject("vec3", "Many people enjoy eating apples as a healthy snack."), new DataObject("vec4", "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."), new DataObject("vec5", "An apple a day keeps the doctor away, as the saying goes."), new DataObject("vec6", "Apple Computer Company was founded on April 1, 1976, by Steve Jobs, Steve Wozniak, and Ronald Wayne as a partnership.") ); List inputs = data.stream() .map(DataObject::getText) .collect(Collectors.toList()); // Specify the embedding model and parameters String embeddingModel = "llama-text-embed-v2"; Map parameters = new HashMap<>(); parameters.put("input_type", "passage"); parameters.put("truncate", "END"); // Generate embeddings for the input data EmbeddingsList embeddings = inference.embed(embeddingModel, parameters, inputs); // Get embedded data List embeddedData = embeddings.getData(); } private static List convertBigDecimalToFloat(List bigDecimalValues) { return bigDecimalValues.stream() .map(BigDecimal::floatValue) .collect(Collectors.toList()); } } class DataObject { private String id; private String text; public DataObject(String id, String text) { this.id = id; this.text = text; } public String getId() { return id; } public String getText() { return text; } } ``` ```go Go theme={null} package main // Import the required packages import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) type Data struct { ID string Text string } type Query struct { Text string } func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() // Initialize a Pinecone client with your API key pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // Define a sample dataset where each item has a unique ID and piece of text data := []Data{ {ID: "vec1", Text: "Apple is a popular fruit known for its sweetness and crisp texture."}, {ID: "vec2", Text: "The tech company Apple is known for its innovative products like the iPhone."}, {ID: "vec3", Text: "Many people enjoy eating apples as a healthy snack."}, {ID: "vec4", Text: "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."}, {ID: "vec5", Text: "An apple a day keeps the doctor away, as the saying goes."}, {ID: "vec6", Text: "Apple Computer Company was founded on April 1, 1976, by Steve Jobs, Steve Wozniak, and Ronald Wayne as a partnership."}, } // Specify the embedding model and parameters embeddingModel := "llama-text-embed-v2" docParameters := pinecone.EmbedParameters{ InputType: "passage", Truncate: "END", } // Convert the text into numerical vectors that Pinecone can index var documents []string for _, d := range data { documents = append(documents, d.Text) } docEmbeddingsResponse, err := pc.Inference.Embed(ctx, &pinecone.EmbedRequest{ Model: embeddingModel, TextInputs: documents, Parameters: docParameters, }) if err != nil { log.Fatalf("Failed to embed documents: %v", err) } else { fmt.Printf(prettifyStruct(docEmbeddingsResponse)) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl https://api.pinecone.io/embed \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "model": "llama-text-embed-v2", "parameters": { "input_type": "passage", "truncate": "END" }, "inputs": [ {"text": "Apple is a popular fruit known for its sweetness and crisp texture."}, {"text": "The tech company Apple is known for its innovative products like the iPhone."}, {"text": "Many people enjoy eating apples as a healthy snack."}, {"text": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."}, {"text": "An apple a day keeps the doctor away, as the saying goes."}, {"text": "Apple Computer Company was founded on April 1, 1976, by Steve Jobs, Steve Wozniak, and Ronald Wayne as a partnership."} ] }' ``` The returned object looks like this: ```python Python theme={null} EmbeddingsList( model='llama-text-embed-v2', data=[ {'values': [0.04925537109375, -0.01313018798828125, -0.0112762451171875, ...]}, ... ], usage={'total_tokens': 130} ) ``` ```javascript JavaScript theme={null} EmbeddingsList(1) [ { values: [ 0.04925537109375, -0.01313018798828125, -0.0112762451171875, ... ] }, ... model: 'llama-text-embed-v2', data: [ { values: [Array] } ], usage: { totalTokens: 130 } ] ``` ```java Java theme={null} class EmbeddingsList { model: llama-text-embed-v2 data: [class Embedding { values: [0.04925537109375, -0.01313018798828125, -0.0112762451171875, ...] additionalProperties: null }, ...] usage: class EmbeddingsListUsage { totalTokens: 130 additionalProperties: null } additionalProperties: null } ``` ```go Go theme={null} { "data": [ { "values": [ 0.03942871, -0.010177612, -0.046051025, ... ] }, ... ], "model": "llama-text-embed-v2", "usage": { "total_tokens": 130 } } ``` ```json curl theme={null} { "data": [ { "values": [ 0.04925537109375, -0.01313018798828125, -0.0112762451171875, ... ] }, ... ], "model": "llama-text-embed-v2", "usage": { "total_tokens": 130 } } ``` ## See also * [Understanding cost](/guides/manage-cost/understanding-cost) * [Manage cost](/guides/manage-cost/manage-cost) # Understanding cost Source: https://docs.pinecone.io/guides/manage-cost/understanding-cost Understand how costs are incurred in Pinecone, including read units (RUs), write units (WUs), storage, egress, and embedding. For the latest pricing details, see [Pricing](https://www.pinecone.io/pricing/). Pinecone serverless is usage-based, so you pay only for the data you store and the operations you run. Idle indexes cost nothing. Most early and small workloads fit within the free [Starter plan](https://www.pinecone.io/pricing/), and you can lower costs further as you scale. ## Ways to reduce cost * **Start free.** The Starter plan has no monthly minimum, so you can build and test before committing to any spend. * **Prepaid credits and annual commitments.** Committing usage upfront earns discounted rates. See [Prepaid credits](#prepaid-credits). * **Bulk import credit.** Standard and Enterprise organizations receive a one-time 1 TB import credit for loading data from object storage. See [Imports](#imports). * **Optimize your workload.** Use namespaces and right-size your reads to cut ongoing query cost. See [Save on costs](/guides/optimize/save-on-costs). * **Talk to us.** Standard and Enterprise customers can [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) to optimize costs and discuss volume discounts. ## Minimum usage The Builder, Standard, and Enterprise [pricing plans](https://www.pinecone.io/pricing/) include a monthly minimum usage commitment: | Plan | Minimum usage | | ---------- | ----------------- | | Starter | \$0/month | | Builder | \$20/month (flat) | | Standard | \$50/month | | Enterprise | \$500/month | On the Builder plan, the monthly minimum is a flat fee that covers included usage; additional usage beyond [Builder limits](/reference/api/database-limits) is blocked rather than billed. On the Standard and Enterprise plans, customers are charged for what they use each month beyond the monthly minimum. The minimum is a commitment you grow into rather than an extra charge. Once your usage exceeds the minimum, you pay only for what you use. **Examples** * You are on the Standard plan. * Your usage for the month of August amounts to \$20. * Your usage is below the \$50 monthly minimum, so your total for the month is \$50. In this case, the August invoice would include line items for each service you used (totaling \$20), plus a single line item covering the rest of the minimum usage commitment (\$30). * You are on the Standard plan. * Your usage for the month of August amounts to \$100. * Your usage exceeds the \$50 monthly minimum, so your total for the month is \$100. In this case, the August invoice would only show line items for each service you used (totaling \$100). Since your usage exceeds the minimum usage commitment, you are only charged for your actual usage and no additional minimum usage line item appears on your invoice. ## Prepaid credits Pinecone offers an incentive for customers who purchase prepaid credits with an upfront payment. Customers may purchase between \$8,000 and \$25,000 in prepaid credits. Customers who purchase prepaid credits can unlock additional usage capacity at no extra cost. The available benefits vary based on the selected plan and prepaid amount. Prepaid credits apply to Pinecone services at List Price. Any usage that exceeds the available prepaid credits will be billed at full List Price. Customers on Standard and Enterprise pay-as-you-go plans can purchase prepaid credits directly by navigating in the Pinecone console to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans). Purchasing prepaid credits is not available through cloud marketplace billing. To purchase prepaid credits through a cloud marketplace, contact [ar@pinecone.io](mailto:ar@pinecone.io). ## Serverless indexes With serverless indexes, you pay for the amount of data stored and operations performed, based on four usage metrics: [read units](#read-units), [write units](#write-units), [storage](#storage), and [egress](#egress). For the latest serverless pricing rates, see [Pricing](https://www.pinecone.io/pricing/). ### Read units A **read unit (RU)** is the unit Pinecone uses to measure and price the cost of a read request. Read units (RUs) measure the compute, I/O, and network resources consumed by the following read requests: * [Query](#query) * [Fetch](#fetch) * [List](#list) Read requests return the number of RUs used. You can use this information to [monitor read costs](/guides/manage-cost/monitor-usage-and-costs#read-units). Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. #### Query The cost of a query scales linearly with the size of the targeted namespace. Specifically, a query uses 1 RU for every 1 GB of namespace size, with a minimum of 0.25 RUs per query. | Namespace size | Read units per query | | :------------- | :------------------- | | \< 0.25 GB | 0.25 RUs (minimum) | | 1 GB | 1 RU | | 10 GB | 10 RUs | | 50 GB | 50 RUs | | 100 GB | 100 RUs | To learn how to calculate your namespace size, see [Storage](#storage). Parameters that affect the size of the query response, such as `top_k`, `include_metadata`, and `include_values`, are not relevant for query cost; only the size of the namespace determines the number of RUs used. #### Fetch A fetch request uses 1 RU for every 10 records fetched, for example: | Fetched records | RUs | | --------------- | --- | | 10 | 1 | | 50 | 5 | | 107 | 11 | Specifying a non-existent ID or adding the same ID more than once does not increase the number of RUs used. However, a fetch request will always use at least 1 RU. [Fetching records by metadata](/guides/manage-data/fetch-data#fetch-records-by-metadata) uses the same cost model as fetching by ID: 1 RU for every 10 records fetched. #### List List has a fixed cost of 1 RU per call, with up to 100 records per call. ### Write units A **write unit (WU)** is the unit Pinecone uses to measure and price the cost of a write request. Write units (WUs) measure the storage and compute resources used by the following write requests: * [Upsert](#upsert) * [Update](#update) * [Delete](#delete) #### Upsert An upsert request uses 1 WU for each 1 KB of the request, with a minimum of 5 WUs per request. When an upsert modifies an existing record, the request uses 1 WU for each 1 KB of the existing record as well. For example, the following table shows the WUs used by upsert requests at different batch sizes and record sizes, assuming all records are new: | Records per batch | Dimension | Avg. metadata size | Avg. record size | WUs | | :---------------- | :-------- | :----------------- | :--------------- | :--- | | 1 | 768 | 100 bytes | 3.2 KB | 5 | | 2 | 768 | 100 bytes | 3.2 KB | 7 | | 10 | 1024 | 15,000 bytes | 19.10 KB | 191 | | 100 | 768 | 500 bytes | 3.57 KB | 357 | | 1000 | 1536 | 1000 bytes | 7.14 KB | 7140 | #### Update An update request uses 1 WU for each 1 KB of the new and existing record, with a minimum of 5 WUs per request. For example, the following table shows the WUs used by an update at different record sizes: | New record size | Previous record size | WUs | | :-------------- | :------------------- | :-- | | 6.24 KB | 6.50 KB | 13 | | 19.10 KB | 15 KB | 25 | | 3.57 KB | 5 KB | 9 | | 7.14 KB | 10 KB | 18 | | 3.17 KB | 3.17 KB | 7 | [Updating records by metadata](/guides/manage-data/update-data#update-by-metadata) uses the same cost model as updating by ID: 1 WU for each 1 KB of the new and existing record. #### Delete A delete request uses 1 WU for each 1 KB of records deleted, with a minimum of 5 WUs per request. For example, the following table shows the WUs used by delete requests at different batch sizes and record sizes: | Records per batch | Dimension | Avg. metadata size | Avg. record size | WUs | | :---------------- | :-------- | :----------------- | :--------------- | :--- | | 1 | 768 | 100 bytes | 3.2 KB | 5 | | 2 | 768 | 100 bytes | 3.2 KB | 7 | | 10 | 1024 | 15,000 bytes | 19.10 KB | 191 | | 100 | 768 | 500 bytes | 3.57 KB | 357 | | 1000 | 1536 | 1000 bytes | 7.14 KB | 7140 | Specifying a non-existent ID or adding the same ID more than once does not increase WU use. [Deleting a namespace](/guides/manage-data/manage-namespaces#delete-a-namespace) or [deleting all records in a namespace using `deleteAll`](/guides/manage-data/delete-data#delete-all-records-in-a-namespace) uses 5 WUs. [Deleting records by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) uses the same cost model as deleting by ID: 1 WU for each 1 KB of records deleted. ### Storage Storage costs are based on the size of an index on a per-gigabyte (GB) monthly rate. The size of an index is defined as the total size of its records across all namespaces. For the latest storage pricing rates, see [Pricing](https://www.pinecone.io/pricing/). A record can include a dense vector, a sparse vector, or both. Use the formula that matches your data to calculate total size:
An [index of dense vectors](/guides/index-data/indexing-overview#indexes-with-dense-vectors) contains records with one dense vector each. Records can also contain sparse vectors (when the index metric is set to `dotproduct`), which can be useful for [hybrid search](/guides/search/hybrid-search#use-a-single-index-for-dense-and-sparse-vectors). To learn how to calculate size in that case, see [Index with both dense and sparse vectors](#index-with-both-dense-and-sparse-vectors). **Calculate size (assuming no sparse vectors)** ``` Index size = Number of records × ( ID size + Metadata size + Dense vector dimensions × 4 bytes ) ``` Where: * `ID size` and `Metadata size` are measured in bytes, averaged across all records. * Each `Dense vector dimension` uses 4 bytes. **Example calculations** These examples assume 8-byte IDs: | Records | Dense vector dimensions | Avg metadata size | Index size | | :--------- | :---------------------- | :---------------- | :--------- | | 500,000 | 768 | 500 bytes | 1.79 GB | | 1,000,000 | 1536 | 1,000 bytes | 7.15 GB | | 5,000,000 | 1024 | 15,000 bytes | 95.5 GB | | 10,000,000 | 1536 | 1,000 bytes | 71.5 GB | Example: 500,000 records × (8-byte ID + (768 dense vector dimensions × 4 bytes) + 500 bytes of metadata) = 1.79 GB An [index of sparse vectors](/guides/index-data/indexing-overview#indexes-with-sparse-vectors) contains records with one sparse vector each. **Calculate size** ``` Index size = Number of records × ( ID size + Metadata size + Number of non-zero sparse values × 8 bytes ) ``` Where: * `ID size` and `Metadata size` are measured in bytes, averaged across all records. * `Number of non-zero sparse values`: Average number across all records. To find the count for a single record, check the length of the sparse vector's `indices` or `values` array. Each non-zero value uses 8 bytes. **Example calculations** These examples assume 8-byte IDs: | Records | Avg number of non-zero sparse values | Avg metadata size | Index size | | :--------- | :----------------------------------- | :---------------- | :--------- | | 500,000 | 10 | 500 bytes | 0.29 GB | | 1,000,000 | 50 | 1,000 bytes | 1.41 GB | | 5,000,000 | 100 | 15,000 bytes | 79.0 GB | | 10,000,000 | 50 | 1,000 bytes | 14.1 GB | Example: 500,000 records × (8-byte ID + (10 non-zero sparse values × 8 bytes) + 500 bytes of metadata) = 0.29 GB An [index with both dense and sparse vectors](/guides/search/hybrid-search#use-a-single-index-for-dense-and-sparse-vectors) contains records that each have one dense vector and an optional sparse vector. **Calculate size** ``` Index size = Number of records × ( ID size + Metadata size + Dense vector dimensions × 4 bytes + Number of non-zero sparse values × 8 bytes ) ``` Where: * `ID size` and `Metadata size` are measured in bytes, averaged across all records. * Each `Dense vector dimension` uses 4 bytes. * `Number of non-zero sparse values`: Average number across all records, including those without sparse vectors. To find the count for a single record, check the length of the sparse vector's `indices` or `values` array. Each non-zero value uses 8 bytes. **Example calculations** These examples assume 8-byte IDs: | Records | Dense vector dimensions | Avg number of non-zero sparse values | Avg metadata size | Index size | | :--------- | :---------------------- | :----------------------------------- | :---------------- | :--------- | | 500,000 | 768 | 10 | 500 bytes | 1.83 GB | | 1,000,000 | 1536 | 50 | 1,000 bytes | 7.54 GB | | 5,000,000 | 1024 | 100 | 15,000 bytes | 99.5 GB | | 10,000,000 | 1536 | 50 | 1,000 bytes | 75.4 GB | Example: 500,000 records × (8-byte ID + (768 dense vector dimensions × 4 bytes) + (10 non-zero sparse values × 8 bytes) + 500 bytes of metadata) = 1.83 GB
### Egress **Egress** measures the data Pinecone returns to you on serverless reads. Egress is measured in GB of total response bytes returned by an in-scope read request, proportional to the record data returned (IDs, scores, values, and metadata). Egress is metered on read requests that return per-record data: * [Query](/guides/search/search-overview) * [Fetch](/guides/manage-data/fetch-data) (by ID and by metadata) * [List](/guides/manage-data/list-record-ids) * [Text search](/reference/api/latest/data-plane/search_records) on integrated indexes * [Full-text search](/guides/search/full-text-search) Write requests (upsert, update, delete, import), index statistics (such as `describe_index_stats`), and index management requests are not metered for egress. Egress accrues on all bytes returned by in-scope reads, including IDs, scores, and metadata. Setting `include_values=false` on a [fetch](/guides/manage-data/fetch-data#fetch-records) or query lowers egress but does not exempt the request, because IDs and metadata are still returned. In-scope read requests return the egress consumed in the response `usage` object. You can use this information to [monitor egress](/guides/manage-cost/monitor-usage-and-costs#egress). #### Egress allowance Each plan includes a monthly egress allowance, which resets at the start of each billing period: | Plan | Monthly egress allowance | | :--------- | :----------------------- | | Free | 1 GB | | Builder | 10 GB | | Standard | 100 GB | | Enterprise | 100 GB | What happens past the allowance depends on your plan: * **Usage-based plans (Standard, Enterprise):** egress beyond the allowance is billed at the per-GB overage rate and reads keep serving. For the latest egress rate, see [Pricing](https://www.pinecone.io/pricing/). * **Flat-fee plans (Free, Builder):** in-scope reads are blocked with a `RESOURCE_EXHAUSTED` (429) error and an upgrade prompt once the allowance is reached. Index statistics, index management, and write requests remain available, and the allowance resets at the start of the next billing period. ## Imports [Importing from object storage](/guides/index-data/import-data) is the most efficient and cost-effective method to load large numbers of records into an index. The cost of an import is based on the size of the records read, whether the records were imported successfully or not. If the import operation fails (e.g., after encountering a vector of the wrong dimension in an import with `on_error="abort"`), you will still be charged for the records read. However, if the import fails because of an internal system error, you will not incur charges. In this case, the import will return the error message `"We were unable to process your request. If the problem persists, please contact us at https://support.pinecone.io"`. Standard and Enterprise organizations receive a **one-time 1 TB bulk import credit**, valid through August 30, 2026. Usage beyond the free allotment is billed at the standard import rate. Builder and Starter plans are not eligible. For the latest import pricing rates, see [Pricing](https://www.pinecone.io/pricing/). ## Backups and restores A [backup](/guides/manage-data/backups-overview) is a static copy of a serverless index. Both the cost of storing a backup and [restoring an index](/guides/manage-data/restore-an-index) from a backup is based on the size of the index. For the latest backup and restore pricing rates, see [Pricing](https://www.pinecone.io/pricing/). ## Embedding Pinecone hosts several [embedding models](/guides/index-data/create-an-index#embedding-models) so it's easy to manage your vector storage and search process on a single platform. You can use a hosted model to embed your data as an integrated part of upserting and querying, or you can use a hosted model to embed your data as a standalone operation. Embedding costs are determined by how many [tokens](https://www.pinecone.io/learn/tokenization/) are in a request. In general, the more words contained in your passage or query, the more tokens you generate. For example, if you generate embeddings for the query, "What is the maximum diameter of a red pine?", Pinecone Inference generates 10 tokens, then converts them into an embedding. If the price per token for your billing plan is \$.08 per million tokens, then this API call costs \$.00001. To learn more about tokenization, see [Choosing an embedding model](https://www.pinecone.io/learn/series/rag/embedding-models-rundown/). For the latest embed pricing rates, see [Pricing](https://www.pinecone.io/pricing/). Embedding requests returns the total tokens generated. You can use this information to [monitor and manage embedding costs](/guides/manage-cost/monitor-usage-and-costs#embedding-tokens). ## Reranking Pinecone hosts several [reranking models](/guides/search/rerank-results#reranking-models) so it's easy to manage two-stage vector retrieval on a single platform. You can use a hosted model to rerank results as an integrated part of a query, or you can use a hosted model to rerank results as a standalone operation. Reranking costs are determined by the number of requests to the reranking model. For the latest rerank pricing rates, see [Pricing](https://www.pinecone.io/pricing/). ## Assistant For details on how costs are incurred in Pinecone Assistant, see [Assistant pricing](/guides/assistant/pricing-and-limits). ## HIPAA compliance add-on Full HIPAA compliance is included with the [Enterprise plan](https://www.pinecone.io/pricing/). For **Standard plan** customers, HIPAA compliance is available as an optional add-on for **\$190 per month**. The add-on is billed monthly and added to your regular invoice. A 6-month minimum period is required. The HIPAA compliance add-on includes: * HIPAA-ready infrastructure * Encrypted data storage * Audit logging * Enhanced security controls * BAA execution and compliance documentation support If you upgrade to the Enterprise plan, the HIPAA compliance add-on is automatically removed because HIPAA compliance is included with Enterprise. ### Enable the HIPAA compliance add-on To enable the HIPAA compliance add-on, [contact sales](mailto:sales@pinecone.io) or [submit a request](https://www.pinecone.io/contact/?contact_form_inquiry_type=Sales). The Pinecone team will review your request and guide you through activation. ## See also * [Manage cost](/guides/manage-cost/manage-cost) * [Monitor usage](/guides/manage-cost/monitor-usage-and-costs) * [Pricing](https://www.pinecone.io/pricing/) # Back up an index Source: https://docs.pinecone.io/guides/manage-data/back-up-an-index Create backups of serverless indexes to protect data, copy indexes, or experiment with configurations using the Pinecone SDK, API, or console. ## Create a backup You can [create a backup from a serverless index](/reference/api/latest/control-plane/create_backup) as follows. Backups are supported for indexes without a schema definition and for integrated embedding indexes that use the records API. They are not supported for full-text search indexes with document schemas that include `full_text_search` string fields, `dense_vector` fields, or `sparse_vector` fields. Indexes with document schemas also do not support `semantic_text` fields. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") backup = pc.create_backup( index_name="docs-example", backup_name="example-backup", description="Monthly backup of production index" ) print(backup) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) const backup = await pc.createBackup({ indexName: 'docs-example', name: 'example-backup', description: 'Monthly backup of production index', }); console.log(backup); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.ApiException; import org.openapitools.db_control.client.model.*; public class CreateBackup { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); String indexName = "docs-example"; String backupName = "example-backup"; String backupDescription = "Monthly backup of production index"; BackupModel backup = pc.createBackup(indexName,backupName, backupDescription); System.out.println(backup); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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) } indexName := "docs-example" backupName := "example-backup" backupDesc := "Monthly backup of production index" backup, err := pc.CreateBackup(ctx, &pinecone.CreateBackupParams{ IndexName: indexName, Name: &backupName, Description: &backupDesc, }) if err != nil { log.Fatalf("Failed to create backup: %v", err) } fmt.Printf(prettifyStruct(backup)) } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="docs-example" curl "https://api.pinecone.io/indexes/$INDEX_NAME/backups" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "example-backup", "description": "Monthly backup of production index" }' ``` The example returns a response like the following: ```python Python theme={null} {'backup_id': '8c85e612-ed1c-4f97-9f8c-8194e07bcf71', 'cloud': 'aws', 'created_at': '2025-05-15T00:52:10.809305882Z', 'description': 'Monthly backup of production index', 'dimension': 1024, 'name': 'example-backup', 'namespace_count': 3, 'record_count': 98, 'region': 'us-east-1', 'size_bytes': 1069169, 'source_index_id': 'f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74', 'source_index_name': 'docs-example', 'status': 'Ready', 'tags': {}} ``` ```javascript JavaScript theme={null} { backupId: '8c85e612-ed1c-4f97-9f8c-8194e07bcf71', sourceIndexName: 'docs-example', sourceIndexId: 'f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74', name: 'example-backup', description: 'Monthly backup of production index', status: 'Ready', cloud: 'aws', region: 'us-east-1', dimension: 1024, metric: undefined, recordCount: 98, namespaceCount: 3, sizeBytes: 1069169, tags: {}, createdAt: '2025-05-14T16:37:25.625540Z' } ``` ```java Java theme={null} class BackupModel { backupId: 0d75b99f-be61-4a93-905e-77201286c02e sourceIndexName: docs-example sourceIndexId: f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74 name: example-backup description: Monthly backup of production index status: Initializing cloud: aws region: us-east-1 dimension: null metric: null recordCount: null namespaceCount: null sizeBytes: null tags: {} createdAt: 2025-05-16T19:42:23.804787550Z additionalProperties: null } ``` ```go Go theme={null} { "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "cloud": "aws", "created_at": "2025-05-15T00:52:10.809305882Z", "description": "Monthly backup of production index", "dimension": 1024, "name": "example-backup", "region": "us-east-1", "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "source_index_name": "docs-example", "status": "Initializing", "tags": {} } ``` ```json curl theme={null} { "backup_id":"8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "source_index_id":"f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "source_index_name":"docs-example", "tags":{}, "name":"example-backup", "description":"Monthly backup of production index", "status":"Ready", "cloud":"aws", "region":"us-east-1", "dimension":1024, "record_count":96, "namespace_count":3, "size_bytes":1069169, "created_at":"2025-05-14T16:37:25.625540Z" } ``` You can create a backup using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups). ## Describe a backup You can [view the details of a backup](/reference/api/latest/control-plane/describe_backup) as follows. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") backup = pc.describe_backup(backup_id="8c85e612-ed1c-4f97-9f8c-8194e07bcf71") print(backup) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) const backupDesc = await pc.describeBackup('8c85e612-ed1c-4f97-9f8c-8194e07bcf71'); console.log(backupDesc); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.ApiException; import org.openapitools.db_control.client.model.*; public class CreateBackup { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); BackupModel backupModel = pc.describeBackup("8c85e612-ed1c-4f97-9f8c-8194e07bcf71"); System.out.println(backupModel); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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) } backup, err := pc.DescribeBackup(ctx, "8c85e612-ed1c-4f97-9f8c-8194e07bcf71") if err != nil { log.Fatalf("Failed to describe backup: %v", err) } fmt.Printf(prettifyStruct(backup)) } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" BACKUP_ID="8c85e612-ed1c-4f97-9f8c-8194e07bcf71" curl -X GET "https://api.pinecone.io/backups/$BACKUP_ID" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "accept: application/json" ``` The example returns a response like the following: ```python Python theme={null} {'backup_id': '8c85e612-ed1c-4f97-9f8c-8194e07bcf71', 'cloud': 'aws', 'created_at': '2025-05-15T00:52:10.809354Z', 'description': 'Monthly backup of production index', 'dimension': 1024, 'name': 'example-backup', 'namespace_count': 3, 'record_count': 98, 'region': 'us-east-1', 'size_bytes': 1069169, 'source_index_id': 'f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74', 'source_index_name': 'docs-example', 'status': 'Ready', 'tags': {}} ``` ```javascript JavaScript theme={null} { backupId: '8c85e612-ed1c-4f97-9f8c-8194e07bcf71', sourceIndexName: 'docs-example', sourceIndexId: 'f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74', name: 'example-backup', description: 'Monthly backup of production index', status: 'Ready', cloud: 'aws', region: 'us-east-1', dimension: 1024, metric: undefined, recordCount: 98, namespaceCount: 3, sizeBytes: 1069169, tags: {}, createdAt: '2025-05-14T16:37:25.625540Z' } ``` ```java Java theme={null} class BackupList { data: [class BackupModel { backupId: 95707edb-e482-49cf-b5a5-312219a51a97 sourceIndexName: docs-example sourceIndexId: f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74 name: example-backup description: Monthly backup of production index status: Initializing cloud: aws region: us-east-1 dimension: null metric: null recordCount: null namespaceCount: null sizeBytes: null tags: {} createdAt: 2025-05-16T19:46:26.248428Z additionalProperties: null }] pagination: null additionalProperties: null } ``` ```go Go theme={null} { "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "cloud": "aws", "created_at": "2025-05-15T00:52:10.809354Z", "description": "Monthly backup of production index", "dimension": 1024, "name": "example-backup", "namespace_count": 3, "record_count": 98, "region": "us-east-1", "size_bytes": 1069169, "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "source_index_name": "docs-example", "status": "Ready", "tags": {} } ``` ```json curl theme={null} { "backup_id":"8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "source_index_id":"f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "source_index_name":"docs-example", "tags":{}, "name":"example-backup", "description":"Monthly backup of production index", "status":"Ready", "cloud":"aws", "region":"us-east-1", "dimension":1024, "record_count":98, "namespace_count":3, "size_bytes":1069169, "created_at":"2025-03-11T18:29:50.549505Z" } ``` You can view backup details using the [Pinecone console](https://app.pinecone.io/organizations/-/projects-/backups). ## List backups for an index You can [list backups for a specific index](/reference/api/latest/control-plane/list_index_backups) as follows. Up to 100 backups are returned at a time by default, in sorted order (bitwise “C” collation). If the `limit` parameter is set, up to that number of backups are returned instead. Whenever there are additional backups to return, the response also includes a `pagination_token` that you can use to get the next batch of backups. When the response does not include a `pagination_token`, there are no more backups to return. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index_backups = pc.list_backups(index_name="docs-example") print(index_backups) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) const indexBackups = await pc.listBackups({ indexName: 'docs-example' }); console.log(indexBackups); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.ApiException; import org.openapitools.db_control.client.model.*; public class CreateBackup { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); String indexName = "docs-example"; BackupList indexBackupList = pc.listIndexBackups(indexName); System.out.println(indexBackupList); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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) } indexName := "docs-example" limit := 2 indexBackups, err := pc.ListBackups(ctx, &pinecone.ListBackupsParams{ Limit: &limit, IndexName: &indexName, }) if err != nil { log.Fatalf("Failed to list backups: %v", err) } fmt.Printf(prettifyStruct(indexBackups)) } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="docs-example" curl -X GET "https://api.pinecone.io/indexes/$INDEX_NAME/backups" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "accept: application/json" ``` The example returns a response like the following: ```python Python theme={null} [{ "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "source_index_name": "docs-example", "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "status": "Ready", "cloud": "aws", "region": "us-east-1", "tags": {}, "name": "example-backup", "description": "Monthly backup of production index", "dimension": 1024, "record_count": 98, "namespace_count": 3, "size_bytes": 1069169, "created_at": "2025-05-15T00:52:10.809305882Z" }] ``` ```javascript JavaScript theme={null} { data: [ { backupId: '8c85e612-ed1c-4f97-9f8c-8194e07bcf71', sourceIndexName: 'docs-example', sourceIndexId: 'f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74', name: 'example-backup', description: 'Monthly backup of production index', status: 'Ready', cloud: 'aws', region: 'us-east-1', dimension: 1024, metric: undefined, recordCount: 98, namespaceCount: 3, sizeBytes: 1069169, tags: {}, createdAt: '2025-05-14T16:37:25.625540Z' } ], pagination: undefined } ``` ```java Java theme={null} class BackupList { data: [class BackupModel { backupId: 8c85e612-ed1c-4f97-9f8c-8194e07bcf71 sourceIndexName: docs-example sourceIndexId: f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74 name: example-backup description: Monthly backup of production index status: Initializing cloud: aws region: us-east-1 dimension: null metric: null recordCount: null namespaceCount: null sizeBytes: null tags: {} createdAt: 2025-05-16T19:46:26.248428Z additionalProperties: null }] pagination: null additionalProperties: null } ``` ```go Go theme={null} { "data": [ { "backup_id": "bf2cda5d-b233-4a0a-aae9-b592780ad3ff", "cloud": "aws", "created_at": "2025-05-16T18:01:51.531129Z", "description": "Monthly backup of production index", "dimension": 0, "name": "example-backup", "namespace_count": 1, "record_count": 96, "region": "us-east-1", "size_bytes": 86393, "source_index_id": "bcb5b3c9-903e-4cb6-8b37-a6072aeb874f", "source_index_name": "docs-example", "status": "Ready", "tags": {} }, { "backup_id": "e12269b0-a29b-4af0-9729-c7771dec03e3", "cloud": "aws", "created_at": "2025-05-14T17:00:45.803146Z", "dimension": 0, "name": "example-backup2", "namespace_count": 1, "record_count": 96, "region": "us-east-1", "size_bytes": 86393, "source_index_id": "bcb5b3c9-903e-4cb6-8b37-a6072aeb874f", "source_index_name": "docs-example", "status": "Ready" } ], "pagination": { "next": "eyJsaW1pdCI6Miwib2Zmc2V0IjoyfQ==" } } ``` ```json curl theme={null} { "data": [ { "backup_id":"9947520e-d5a1-4418-a78d-9f464c9969da", "source_index_id":"8433941a-dae7-43b5-ac2c-d3dab4a56b2b", "source_index_name":"docs-example", "tags":{}, "name":"example-backup", "description":"Monthly backup of production index", "status":"Pending", "cloud":"aws", "region":"us-east-1", "dimension":1024, "record_count":98, "namespace_count":3, "size_bytes":1069169, "created_at":"2025-03-11T18:29:50.549505Z" } ], "pagination":null } ``` You can view the backups for a specific index from either the [Backups](https://app.pinecone.io/organizations/-/projects/-/backups) tab or the [Indexes](https://app.pinecone.io/organizations/-/projects/-/indexes) tab in the Pinecone console. ## List backups in a project You can [list backups for all indexes in a project](/reference/api/latest/control-plane/list_project_backups) as follows. Up to 100 backups are returned at a time by default, in sorted order (bitwise “C” collation). If the `limit` parameter is set, up to that number of backups are returned instead. Whenever there are additional backups to return, the response also includes a `pagination_token` that you can use to get the next batch of backups. When the response does not include a `pagination_token`, there are no more backups to return. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") project_backups = pc.list_backups() print(project_backups) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) const projectBackups = await pc.listBackups(); console.log(projectBackups); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.ApiException; import org.openapitools.db_control.client.model.*; public class CreateBackup { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); String indexName = "docs-example"; BackupList projectBackupList = pc.listProjectBackups(); System.out.println(projectBackupList); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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) } limit := 3 backups, err := pc.ListBackups(ctx, &pinecone.ListBackupsParams{ Limit: &limit, }) if err != nil { log.Fatalf("Failed to list backups: %v", err) } fmt.Printf(prettifyStruct(backups)) } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -X GET "https://api.pinecone.io/backups" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "accept: application/json" ``` The example returns a response like the following: ```python Python theme={null} [{ "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "source_index_name": "docs-example", "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "status": "Ready", "cloud": "aws", "region": "us-east-1", "tags": {}, "name": "example-backup", "description": "Monthly backup of production index", "dimension": 1024, "record_count": 98, "namespace_count": 3, "size_bytes": 1069169, "created_at": "2025-05-15T20:26:21.248515Z" }, { "backup_id": "95707edb-e482-49cf-b5a5-312219a51a97", "source_index_name": "docs-example2", "source_index_id": "b49f27d1-1bf3-49c6-82b5-4ae46f00f0e6", "status": "Ready", "cloud": "aws", "region": "us-east-1", "tags": {}, "name": "example-backup2", "description": "Monthly backup of production index", "dimension": 1024, "record_count": 97, "namespace_count": 2, "size_bytes": 1069169, "created_at": "2025-05-15T00:52:10.809354Z" }, { "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "source_index_name": "docs-example3", "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "status": "Ready", "cloud": "aws", "region": "us-east-1", "tags": {}, "name": "example-backup3", "description": "Monthly backup of production index", "dimension": 1024, "record_count": 98, "namespace_count": 3, "size_bytes": 1069169, "created_at": "2025-05-14T16:37:25.625540Z" }] ``` ```javascript JavaScript theme={null} { data: [ { backupId: 'e12269b0-a29b-4af0-9729-c7771dec03e3', sourceIndexName: 'docs-example', sourceIndexId: 'bcb5b3c9-903e-4cb6-8b37-a6072aeb874f', name: 'example-backup', description: undefined, status: 'Ready', cloud: 'aws', region: 'us-east-1', dimension: 0, metric: undefined, recordCount: 96, namespaceCount: 1, sizeBytes: 86393, tags: undefined, createdAt: '2025-05-14T17:00:45.803146Z' }, { backupId: 'd686451d-1ede-4004-9f72-7d22cc799b6e', sourceIndexName: 'docs-example2', sourceIndexId: 'b49f27d1-1bf3-49c6-82b5-4ae46f00f0e6', name: 'example-backup2', description: undefined, status: 'Ready', cloud: 'aws', region: 'us-east-1', dimension: 1024, metric: undefined, recordCount: 50, namespaceCount: 1, sizeBytes: 545171, tags: undefined, createdAt: '2025-05-14T17:00:34.814371Z' }, { backupId: '8c85e612-ed1c-4f97-9f8c-8194e07bcf71', sourceIndexName: 'docs-example3', sourceIndexId: 'f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74', name: 'example-backup3', description: 'Monthly backup of production index', status: 'Ready', cloud: 'aws', region: 'us-east-1', dimension: 1024, metric: undefined, recordCount: 98, namespaceCount: 3, sizeBytes: 1069169, tags: {}, createdAt: '2025-05-14T16:37:25.625540Z' } ], pagination: undefined } ``` ```java Java theme={null} class BackupList { data: [class BackupModel { backupId: 13761d20-7a0b-4778-ac27-36dd91c4be43 sourceIndexName: example-dense-index sourceIndexId: f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74 name: example-backup description: Monthly backup of production index status: Initializing cloud: aws region: us-east-1 dimension: null metric: null recordCount: null namespaceCount: null sizeBytes: null tags: {} createdAt: 2025-05-16T19:46:26.248428Z additionalProperties: null }, class BackupModel { backupId: 0d75b99f-be61-4a93-905e-77201286c02e sourceIndexName: example-dense-index sourceIndexId: f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74 name: example-backup2 description: Monthly backup of production index status: Initializing cloud: aws region: us-east-1 dimension: null metric: null recordCount: null namespaceCount: null sizeBytes: null tags: {} createdAt: 2025-05-16T19:42:23.804820Z additionalProperties: null }, class BackupModel { backupId: bf2cda5d-b233-4a0a-aae9-b592780ad3ff sourceIndexName: example-sparse-index sourceIndexId: bcb5b3c9-903e-4cb6-8b37-a6072aeb874f name: example-backup3 description: Monthly backup of production index status: Ready cloud: aws region: us-east-1 dimension: 0 metric: null recordCount: 96 namespaceCount: 1 sizeBytes: 86393 tags: {} createdAt: 2025-05-16T18:01:51.531129Z additionalProperties: null }] pagination: null additionalProperties: null } ``` ```go Go theme={null} { "data": [ { "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "cloud": "aws", "created_at": "2025-05-15T00:52:10.809305882Z", "description": "Monthly backup of production index", "dimension": 1024, "name": "example-backup", "namespace_count": 3, "record_count": 98, "region": "us-east-1", "size_bytes": 1069169, "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "source_index_name": "docs-example", "status": "Ready", "tags": {} }, { "backup_id": "bf2cda5d-b233-4a0a-aae9-b592780ad3ff", "cloud": "aws", "created_at": "2025-05-15T00:52:10.809305882Z", "description": "Monthly backup of production index", "dimension": 0, "name": "example-backup2", "namespace_count": 1, "record_count": 96, "region": "us-east-1", "size_bytes": 86393, "source_index_id": "bcb5b3c9-903e-4cb6-8b37-a6072aeb874f", "source_index_name": "example-sparse-index", "status": "Ready", "tags": {} }, { "backup_id": "f73028f6-1746-410e-ab6d-9dd2519df4de", "cloud": "aws", "created_at": "2025-05-15T20:26:21.248515Z", "description": "Monthly backup of production index", "dimension": 1024, "name": "example-backup3", "namespace_count": 2, "record_count": 97, "region": "us-east-1", "size_bytes": 1069169, "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "source_index_name": "example-dense-index", "status": "Ready", "tags": {} } ], "pagination": { "next": "eyJsaW1pdCI6Miwib2Zmc2V0IjoyfQ==" } } ``` ```json curl theme={null} { "data": [ { "backup_id": "e12269b0-a29b-4af0-9729-c7771dec03e3", "source_index_id": "bcb5b3c9-903e-4cb6-8b37-a6072aeb874f", "source_index_name": "docs-example", "tags": null, "name": "example-backup", "description": null, "status": "Ready", "cloud": "aws", "region": "us-east-1", "dimension": 0, "record_count": 96, "namespace_count": 1, "size_bytes": 86393, "created_at": "2025-05-14T17:00:45.803146Z" }, { "backup_id": "d686451d-1ede-4004-9f72-7d22cc799b6e", "source_index_id": "b49f27d1-1bf3-49c6-82b5-4ae46f00f0e6", "source_index_name": "docs-example2", "tags": null, "name": "example-backup2", "description": null, "status": "Ready", "cloud": "aws", "region": "us-east-1", "dimension": 1024, "record_count": 50, "namespace_count": 1, "size_bytes": 545171, "created_at": "2025-05-14T17:00:34.814371Z" }, { "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "source_index_name": "docs-example3", "tags": {}, "name": "example-backup3", "description": "Monthly backup of production index", "status": "Ready", "cloud": "aws", "region": "us-east-1", "dimension": 1024, "record_count": 98, "namespace_count": 3, "size_bytes": 1069169, "created_at": "2025-05-14T16:37:25.625540Z" } ], "pagination": null } ``` You can view all backups in a project using the [Pinecone console](https://app.pinecone.io/organizations/-/projects-/backups). ## Delete a backup You can [delete a backup](/reference/api/latest/control-plane/delete_backup) as follows. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.delete_backup(backup_id="9947520e-d5a1-4418-a78d-9f464c9969da") ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) await pc.deleteBackup('9947520e-d5a1-4418-a78d-9f464c9969da'); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.ApiException; import org.openapitools.db_control.client.model.*; public class CreateBackup { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.deleteBackup("9947520e-d5a1-4418-a78d-9f464c9969da"); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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) } err = pc.DeleteBackup(ctx, "8c85e612-ed1c-4f97-9f8c-8194e07bcf71") if err != nil { log.Fatalf("Failed to delete backup: %v", err) } else { fmt.Println("Backup deleted successfully") } } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" BACKUP_ID="9947520e-d5a1-4418-a78d-9f464c9969da" curl -X DELETE "https://api.pinecone.io/backups/$BACKUP_ID" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` You can delete a backup using the [Pinecone console](https://app.pinecone.io/organizations/-/projects-/backups). ## Schedule automated backups Instead of creating backups manually, you can define a recurring schedule that automatically creates backups at a daily, weekly, or monthly frequency. Each schedule includes a retention policy that automatically deletes old backups, keeping storage costs predictable. Each index supports one active schedule at a time. ### Create a backup schedule 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups) and go to the **Backups** tab. 2. Find your index and, in the **Schedule** column, click **add**. Alternatively, select **Schedule backups** from the actions menu of the index. 3. In the **Add a backup schedule** modal, select a **Frequency** (daily, weekly, or monthly). 4. Select a **Retention** period. Each backup created by the schedule is automatically deleted after this period. 5. Click **Add schedule**. Pinecone names the schedule and assigns its run time automatically. The scheduled backups API requires `X-Pinecone-API-Version: unstable`. To [create a backup schedule](/reference/api/2026-04/control-plane/create_backup_schedule): ```bash curl theme={null} curl -sS -X POST "https://api.pinecone.io/indexes/${INDEX_NAME}/backup-schedules" \ -H "api-key: ${PINECONE_API_KEY}" \ -H "X-Pinecone-API-Version: unstable" \ -H "Content-Type: application/json" \ -d '{ "name": "my-nightly-backup", "schedule": { "type": "time-based", "frequency": "daily" }, "retention": { "expire_after_days": 7 } }' ``` Use `"frequency": "weekly"` or `"monthly"` as needed. The retention policy (`expire_after_days`) is required. ### Manage backup schedules 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups) and go to the **Backups** tab. 2. Find your index and, in the **Schedule** column, click the schedule. This opens the **Scheduled backups** page for the index. For each schedule, the page shows the frequency, retention period, and next scheduled run time. From here, you can: * **Pause or resume a schedule**: Use the toggle on the schedule. An index can have up to three schedules, but only one can be enabled at a time. * **Edit a schedule**: Expand the schedule, change the **Frequency** or **Retention**, and click **Update**. * **Delete a schedule**: Select **Delete** from the actions menu of the schedule. The scheduled backups API requires `X-Pinecone-API-Version: unstable`. You can [list schedules](/reference/api/2026-04/control-plane/list_backup_schedules), [update a schedule](/reference/api/2026-04/control-plane/update_backup_schedule) (e.g., to pause it or change the frequency), [delete a schedule](/reference/api/2026-04/control-plane/delete_backup_schedule), and [view the backup history](/reference/api/2026-04/control-plane/list_backup_schedule_history) for a schedule. Deleting a schedule does not delete any backups that were previously created by it. For more details, see [Scheduled backups](/guides/manage-data/backups-overview#scheduled-backups). # Backups overview Source: https://docs.pinecone.io/guides/manage-data/backups-overview Learn how serverless index backups work in Pinecone, including scheduled backups, retention policies, and use cases for restoring or copying data. A backup is a static copy of a serverless [index](/guides/index-data/indexing-overview) that only consumes storage. It is a non-queryable representation of a set of records. You can [create a backup](/guides/manage-data/back-up-an-index) of a serverless index, and you can [create a new serverless index from a backup](/guides/manage-data/restore-an-index). This allows you to restore the index with the same or different configurations. ## Use cases Creating a backup is useful when performing tasks like the following: * Protecting an index from manual or system failures. * Temporarily shutting down an index. * Copying the data from one index into a different index. * Making a backup of your index. * Experimenting with different index configurations. ## Scheduled backups Instead of creating backups manually, you can define a recurring backup schedule that runs automatically. Each schedule includes: * **Frequency**: Backups can run daily, weekly, or monthly. * **Retention**: A required expiration policy that automatically deletes old backups, keeping storage costs predictable. Each index supports one active schedule at a time. Backups created by a schedule are automatically named `{name}-{ISO8601_timestamp}`. You can create and manage backup schedules in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups) or with the API. For step-by-step instructions, see [Schedule automated backups](/guides/manage-data/back-up-an-index#schedule-automated-backups). The scheduled backups API requires `X-Pinecone-API-Version: unstable`. For example, to create a daily backup that expires after 7 days: ```bash theme={null} curl -sS -X POST "https://api.pinecone.io/indexes/${INDEX_NAME}/backup-schedules" \ -H "api-key: ${PINECONE_API_KEY}" \ -H "X-Pinecone-API-Version: unstable" \ -H "Content-Type: application/json" \ -d '{ "name": "my-nightly-backup", "schedule": { "type": "time-based", "frequency": "daily" }, "retention": { "expire_after_days": 7 } }' ``` Deleting a schedule does not delete any backups that were previously created by it. If you delete an index, all associated schedules are automatically deleted. For more details, see the API reference: * [Create backup schedule](/reference/api/2026-04/control-plane/create_backup_schedule) * [List backup schedules](/reference/api/2026-04/control-plane/list_backup_schedules) * [Describe backup schedule](/reference/api/2026-04/control-plane/describe_backup_schedule) * [Update backup schedule](/reference/api/2026-04/control-plane/update_backup_schedule) * [Delete backup schedule](/reference/api/2026-04/control-plane/delete_backup_schedule) * [List schedule history](/reference/api/2026-04/control-plane/list_backup_schedule_history) ## Performance Backup and restore times depend upon the size of the index and number of namespaces: * For less than 1M vectors in a namespace, backups and restores take approximately 10 minutes. * For 100,000,000 vectors, backups and restores can take up to 5 hours. ## Quotas | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :------------------ | :----------- | :----------- | :------------ | :-------------- | | Backups per project | N/A | N/A | 500 | 1000 | Backups are not available on the Starter or Builder plans. To create backups, [upgrade to the Standard or Enterprise plan](/guides/organizations/manage-billing/upgrade-billing-plan). ## Limitations Backup limitations are as follows: * Backups are stored in the same project, cloud provider, and region as the source index. * You can only restore an index to the same project and cloud provider as the source index. Restoring to a different region on the same cloud provider is supported using the `unstable` API version. For details, see [Restore to a different region](/guides/manage-data/restore-an-index#restore-to-a-different-region). * Backups only include vectors that were in the index at least 15 minutes prior to the backup time. This means that if a vector was inserted into an index and a backup was immediately taken after, the recently inserted vector may not be backed up. More specifically, if a backup is created only a few minutes after the source index was created, the backup may have 0 vectors. * You can only perform operations on backups in the current Pinecone project. * Backups are supported for indexes without a schema definition and for integrated embedding indexes that use the records API. They are not supported for full-text search indexes with document schemas that include `full_text_search` string fields, `dense_vector` fields, or `sparse_vector` fields. Indexes with document schemas also do not support `semantic_text` fields. ## Backup and restore cost * To understand how cost is calculated for backups and restores, see [Understanding cost](/guides/manage-cost/understanding-cost#backups-and-restores). * For up-to-date pricing information, see [Pricing](https://www.pinecone.io/pricing/). # Delete records Source: https://docs.pinecone.io/guides/manage-data/delete-data Delete records from a Pinecone index namespace by ID or metadata filter, including delete-by-ID, delete-all, and delete-by-metadata operations. This page shows you how to [delete](/reference/api/latest/data-plane/delete) records from an index [namespace](/guides/index-data/indexing-overview#namespaces). Deletes consume [write units (WUs)](/guides/manage-cost/understanding-cost#write-units). See [Understanding cost](/guides/manage-cost/understanding-cost#delete) for how delete cost is calculated. ## Delete records by ID Since Pinecone records can always be efficiently accessed using their ID, deleting by ID is the most efficient way to remove specific records from a namespace. To remove records from the default namespace, specify `"__default__"` as the namespace in your request. ```Python Python theme={null} # pip install "pinecone[grpc]" from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.delete(ids=["id-1", "id-2"], namespace='example-namespace') ``` ```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/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const ns = index.namespace('example-namespace') // Delete one record by ID. await ns.deleteOne('id-1'); // Delete more than one record by ID. await ns.deleteMany(['id-2', 'id-3']); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import java.util.Arrays; import java.util.List; public class DeleteExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); List ids = Arrays.asList("id-1", "id-2"); index.deleteByIds(ids, "example-namespace"); } } ``` ```go Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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/manage-data/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) } id1 := "id-1" id2 := "id-2" err = idxConnection.DeleteVectorsById(ctx, []string{id1, id2}) if err != nil { log.Fatalf("Failed to delete vector with ID %v: %v", id, err) } } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/vectors/delete" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "ids": [ "id-1", "id-2" ], "namespace": "example-namespace" } ' ``` ## Delete records by metadata To delete records from a namespace based on their metadata values, pass a [metadata filter expression](/guides/index-data/indexing-overview#metadata-filter-expressions) to the `delete` operation. This deletes all records in the namespace that match the filter expression. For example, the following code deletes all records with a `genre` field set to `documentary` from namespace `example-namespace`: ```Python Python theme={null} # pip install "pinecone[grpc]" from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.delete( filter={ "genre": {"$eq": "documentary"} }, namespace="example-namespace" ) ``` ```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/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const ns = index.namespace('example-namespace') await ns.deleteMany({ genre: { $eq: "documentary" }, }); ``` ```java Java theme={null} import com.google.protobuf.Struct; import com.google.protobuf.Value; import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import java.util.Arrays; import java.util.List; public class DeleteExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); Struct filter = Struct.newBuilder() .putFields("genre", Value.newBuilder() .setStructValue(Struct.newBuilder() .putFields("$eq", Value.newBuilder() .setStringValue("documentary") .build())) .build()) .build(); index.deleteByFilter(filter, "example-namespace"); } } ``` ```go Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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/manage-data/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) } metadataFilter := map[string]interface{}{ "genre": map[string]interface{}{ "$eq": "documentary", }, } filter, err := structpb.NewStruct(metadataFilter) if err != nil { log.Fatalf("Failed to create metadata filter: %v", err) } err = idxConnection.DeleteVectorsByFilter(ctx, filter) if err != nil { log.Fatalf("Failed to delete vector(s) with filter %+v: %v", filter, err) } } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -i "https://$INDEX_HOST/vectors/delete" \ -H 'Api-Key: $PINECONE_API_KEY' \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "filter": {"genre": {"$eq": "documentary"}}, "namespace": "example-namespace" }' ``` ## Delete all records in a namespace To delete all of the records in a namespace but not the namespace itself, provide a `namespace` parameter and specify the appropriate `deleteAll` parameter for your SDK. To target the default namespace, set `namespace` to `"__default__"`. ```Python Python theme={null} # pip install "pinecone[grpc]" from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.delete(delete_all=True, namespace='example-namespace') ``` ```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/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") await index.namespace('example-namespace').deleteAll(); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import java.util.Arrays; import java.util.List; public class DeleteExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); index.deleteAll("example-namespace"); } } ``` ```go Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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/manage-data/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) } err = idxConnection.DeleteAllVectorsInNamespace(ctx) if err != nil { log.Fatalf("Failed to delete all vectors in namespace %v: %v", namespace, err) } } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/vectors/delete" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "deleteAll": true, "namespace": "example-namespace" } ' ``` ## Delete an entire namespace To delete an entire namespace and all of its records, see [Delete a namespace](/guides/manage-data/manage-namespaces#delete-a-namespace). ## Delete an entire index To remove all records from an index, [delete the index](/guides/manage-data/manage-indexes#delete-an-index) and [recreate it](/guides/index-data/create-an-index). ## Delete limits **Delete by ID limits:** | Metric | Limit | | :------------------ | :--------------------------------------------- | | Max IDs per request | 1000 IDs | | Max request rate | 5000 records per second per index or namespace | **Delete by metadata limits:** | Metric | Limit | | :--------------- | :------------------------------------------------------------------------- | | Max request rate | 5 requests per second per namespace
500 requests per second per index | ## Data freshness Pinecone is eventually consistent, so there can be a slight delay before new or changed records are visible to queries. You can view index stats to [check data freshness](/guides/index-data/check-data-freshness). # Fetch records Source: https://docs.pinecone.io/guides/manage-data/fetch-data Retrieve full Pinecone records by ID from a namespace to inspect vector values, metadata, and IDs, or verify upserts using the fetch operation. You can fetch data using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes/-/browser). Fetches consume [read units (RUs)](/guides/manage-cost/understanding-cost#read-units). See [Understanding cost](/guides/manage-cost/understanding-cost#fetch) for how fetch cost is calculated. ## Fetch records by ID To fetch records from a namespace based on their IDs, use the `fetch` operation with the following parameters: * `namespace`: The [namespace](/guides/index-data/indexing-overview#namespaces) containing the records to fetch. To use the default namespace, set this to `"__default__"`. * `ids`: The IDs of the records to fetch. Maximum of 1000. For on-demand indexes, since vector values are retrieved from object storage, fetch operations may have increased latency. If you only need metadata or IDs, consider using the [`query`](/reference/api/latest/data-plane/query) operation with `include_values` set to `false` instead. See [Decrease latency](/guides/optimize/decrease-latency#avoid-including-vector-values-when-not-needed) for more details. ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.fetch(ids=["id-1", "id-2"], namespace="example-namespace") ``` ```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/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const fetchResult = await index.namespace('example-namespace').fetch(['id-1', 'id-2']); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.proto.FetchResponse; import java.util.Arrays; import java.util.List; public class FetchExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); List ids = Arrays.asList("id-1", "id-2"); FetchResponse fetchResponse = index.fetch(ids, "example-namespace"); System.out.println(fetchResponse); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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/manage-data/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) } res, err := idxConnection.FetchVectors(ctx, []string{"id-1", "id-2"}) if err != nil { log.Fatalf("Failed to fetch vectors: %v", err) } else { fmt.Printf(prettifyStruct(res)) } } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/vectors/fetch?ids=id-1&ids=id-2&namespace=example-namespace" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` The response looks like this: ```Python Python theme={null} {'namespace': 'example-namespace', 'usage': {'readUnits': 1}, 'vectors': {'id-1': {'id': 'id-1', 'values': [0.568879, 0.632687092, 0.856837332, ...]}, 'id-2': {'id': 'id-2', 'values': [0.00891787093, 0.581895, 0.315718859, ...]}}} ``` ```JavaScript JavaScript theme={null} {'namespace': 'example-namespace', 'usage': {'readUnits': 1}, 'records': {'id-1': {'id': 'id-1', 'values': [0.568879, 0.632687092, 0.856837332, ...]}, 'id-2': {'id': 'id-2', 'values': [0.00891787093, 0.581895, 0.315718859, ...]}}} ``` ```java Java theme={null} namespace: "example-namespace" vectors { key: "id-1" value { id: "id-1" values: 0.568879 values: 0.632687092 values: 0.856837332 ... } } vectors { key: "id-2" value { id: "id-2" values: 0.00891787093 values: 0.581895 values: 0.315718859 ... } } usage { read_units: 1 } ``` ```go Go theme={null} { "vectors": { "id-1": { "id": "id-1", "values": [ -0.0089730695, -0.020010853, -0.0042787646, ... ] }, "id-2": { "id": "id-2", "values": [ -0.005380766, 0.00215196, -0.014833462, ... ] } }, "usage": { "read_units": 1 } } ``` ```json curl theme={null} { "vectors": { "id-1": { "id": "id-1", "values": [0.568879, 0.632687092, 0.856837332, ...] }, "id-2": { "id": "id-2", "values": [0.00891787093, 0.581895, 0.315718859, ...] } }, "namespace": "example-namespace", "usage": {"readUnits": 1}, } ``` ## Fetch records by metadata To fetch records from a namespace based on their metadata values, use the `fetch_by_metadata` operation with the following parameters: | Parameter | Required | Description | | :---------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `filter` | Yes | A [metadata filter expression](/guides/index-data/indexing-overview#metadata-filter-expressions) describing the records to fetch. Must be present and non-empty. | | `limit` | No | The maximum number of matching records to return in a single response. Defaults to 100; maximum 10,000. To retrieve more than 10,000 matching records, paginate using `paginationToken`. | | `namespace` | No | The [namespace](/guides/index-data/indexing-overview#namespaces) containing the records to fetch. If omitted or set to an empty string, defaults to the default namespace. To explicitly use the default namespace, set this to `"__default__"`. | | `paginationToken` | No | The `next` token value from the `pagination` object found in a previous response. Include this value to fetch the next page of results, or omit it to start from the beginning. Must be used with the same `namespace` and `filter` parameters that generated it — using an existing token with different parameters will return incorrect results. | For example, the following code fetches 2 records with a `genre` field set to `Action/Adventure` from the default namespace: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") results = index.fetch_by_metadata( filter={"genre": {"$eq": "Action/Adventure"}}, namespace="__default__", limit=2 ) print(results) ``` ```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/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const results = await index.fetchByMetadata({ filter: { genre: { $eq: 'Action/Adventure' } }, namespace: '__default__', limit: 2 }); console.log(results); ``` ```java Java theme={null} import com.google.protobuf.Struct; import com.google.protobuf.Value; import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.proto.FetchByMetadataResponse; public class FetchByMetadataExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); Struct filter = Struct.newBuilder() .putFields("genre", Value.newBuilder() .setStructValue(Struct.newBuilder() .putFields("$eq", Value.newBuilder() .setStringValue("Action/Adventure") .build()) .build()) .build()) .build(); FetchByMetadataResponse response = index.fetchByMetadata( "__default__", filter, 2, null); System.out.println(response); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" "google.golang.org/protobuf/types/known/structpb" ) 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/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } filter, err := structpb.NewStruct(map[string]interface{}{ "genre": map[string]interface{}{ "$eq": "Action/Adventure", }, }) if err != nil { log.Fatalf("Failed to create filter: %v", err) } namespace := "__default__" limit := uint32(2) res, err := idxConnection.FetchVectorsByMetadata(ctx, &pinecone.FetchVectorsByMetadataRequest{ Filter: filter, Namespace: &namespace, Limit: &limit, }) if err != nil { log.Fatalf("Failed to fetch vectors by metadata: %v", err) } fmt.Printf(prettifyStruct(res)) } ``` ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X POST "https://$INDEX_HOST/vectors/fetch_by_metadata" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "namespace": "__default__", "filter": {"genre": {"$eq": "Action/Adventure"}}, "limit": 2 }' ``` The response looks like this: ```json theme={null} { "vectors": { "0": { "id": "0", "values": [ 0.0234527588, 0.0291595459 ... ], "metadata": { "box-office": 2923706026, "genre": "Action/Adventure", "summary": "On the alien world of Pandora, paraplegic Marine Jake Sully uses an avatar to walk again and becomes torn between his mission and protecting the planet's indigenous Na'vi people. The film stars Sam Worthington, Zoe Saldana, and Sigourney Weaver.", "title": "Avatar", "year": 2009 } }, "1": { "id": "1", "values": [ 0.0397644043, 0.013053894, ... ], "metadata": { "box-office": 2799439100, "genre": "Action/Adventure", "summary": "In the aftermath of Thanos wiping out half of the universe, the remaining Avengers assemble once more to undo the chaos, leading to a time-traveling adventure. Stars Robert Downey Jr., Chris Evans, and Scarlett Johansson.", "title": "Avengers: Endgame", "year": 2019 } } }, "namespace": "__default__", "usage": { "readUnits": 1 }, "pagination": { "next": "Tm90aGluZyB0byBzZWUgaGVyZQo=" } } ``` To fetch the next page of results, pass the pagination token from the previous response. For example: ```Python Python theme={null} next_results = index.fetch_by_metadata( filter={"genre": {"$eq": "Action/Adventure"}}, namespace="__default__", limit=2, pagination_token="Tm90aGluZyB0byBzZWUgaGVyZQo=" ) ``` ```JavaScript JavaScript theme={null} const nextResults = await index.fetchByMetadata({ filter: { genre: { $eq: 'Action/Adventure' } }, namespace: '__default__', limit: 2, paginationToken: 'Tm90aGluZyB0byBzZWUgaGVyZQo=' }); ``` ```java Java theme={null} FetchByMetadataResponse nextPage = index.fetchByMetadata( "__default__", filter, 2, "Tm90aGluZyB0byBzZWUgaGVyZQo="); ``` ```go Go theme={null} paginationToken := "Tm90aGluZyB0byBzZWUgaGVyZQo=" nextRes, err := idxConnection.FetchVectorsByMetadata(ctx, &pinecone.FetchVectorsByMetadataRequest{ Filter: filter, Namespace: &namespace, Limit: &limit, PaginationToken: &paginationToken, }) ``` ```shell curl theme={null} curl -X POST "https://$INDEX_HOST/vectors/fetch_by_metadata" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "namespace": "__default__", "filter": {"genre": {"$eq": "Action/Adventure"}}, "limit": 2, "paginationToken": "Tm90aGluZyB0byBzZWUgaGVyZQo=" }' ``` When there are more results available, the response includes a `pagination` object with a `next` token. When there are no more results, the response does not include a `pagination` object. ## Fetch limits **Fetch by ID limits:** | Metric | Limit | | :------------------ | :-------------------------------- | | Max IDs per request | 1000 IDs | | Max request size | N/A | | Max request rate | 100 requests per second per index | **Fetch by metadata limits:** | Metric | Limit | | :----------------------- | :---------------------------------- | | Max records per response | 10,000 records | | Max response size | 4 MB | | Max request rate | 5 requests per second per namespace | To retrieve more than 10,000 matching records, paginate through results using the `paginationToken` parameter. See [Fetch records by metadata](#fetch-records-by-metadata). ## Data freshness Pinecone is eventually consistent, so there can be a slight delay before new or changed records are visible to queries. You can view index stats to [check data freshness](/guides/index-data/check-data-freshness). # List record IDs Source: https://docs.pinecone.io/guides/manage-data/list-record-ids List the IDs of records in a Pinecone serverless namespace, filter by ID prefix, and paginate results to verify upserts cheaply and quickly. You can list the IDs of all records in a [namespace](/guides/index-data/indexing-overview#namespaces) or just the records with a common ID prefix. Using `list` to get record IDs and not the associated data is a cheap and fast way to check [upserts](/guides/index-data/upsert-data). The `list` endpoint is supported only for serverless indexes. ## List the IDs of all records in a namespace To list the IDs of all records in the namespace of a serverless index, pass only the `namespace` parameter: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key='YOUR_API_KEY') # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") for ids in index.list(namespace='example-namespace'): print(ids) # Response: # ['doc1#chunk1', 'doc1#chunk2', 'doc1#chunk3'] ``` ```js JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone(); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace"); const results = await index.listPaginated(); console.log(results); // { // vectors: [ // { id: 'doc1#01' }, { id: 'doc1#02' }, { id: 'doc1#03' }, // { id: 'doc1#04' }, { id: 'doc1#05' }, { id: 'doc1#06' }, // { id: 'doc1#07' }, { id: 'doc1#08' }, { id: 'doc1#09' }, // ... // ], // pagination: { // next: 'eyJza2lwX3Bhc3QiOiJwcmVUZXN0LS04MCIsInByZWZpeCI6InByZVRlc3QifQ==' // }, // namespace: 'example-namespace', // usage: { readUnits: 1 } // } // Fetch the next page of results await index.listPaginated({ prefix: 'doc1#', paginationToken: results.pagination.next}); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.proto.ListResponse; public class ListExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); // get the pagination token String paginationToken = index.list("example-namespace", 3).getPagination().getNext(); // get vectors with limit 3 with the paginationToken obtained from the previous step ListResponse listResponse = index.list("example-namespace", 3, paginationToken); } } // Response: // vectors { // id: "doc1#chunk1" // } // vectors { // id: "doc1#chunk2" // } // vectors { // id: "doc2#chunk1" // } // vectors { // id: "doc3#chunk1" // } // pagination { // next: "eyJza2lwX3Bhc3QiOiJhbHN0cm9lbWVyaWEtcGVydXZpYW4iLCJwcmVmaXgiOm51bGx9" // } // namespace: "example-namespace" // usage { // read_units: 1 // } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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/manage-data/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) } limit := uint32(3) res, err := idxConnection.ListVectors(ctx, &pinecone.ListVectorsRequest{ Limit: &limit, }) if len(res.VectorIds) == 0 { fmt.Println("No vectors found") } else { fmt.Printf(prettifyStruct(res)) } } // Response: // { // "vector_ids": [ // "doc1#chunk1", // "doc1#chunk2", // "doc1#chunk3" // ], // "usage": { // "read_units": 1 // }, // "next_pagination_token": "eyJza2lwX3Bhc3QiOiIwMDBkMTc4OC0zMDAxLTQwZmMtYjZjNC0wOWI2N2I5N2JjNDUiLCJwcmVmaXgiOm51bGx9" // } ``` ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/vectors/list?namespace=example-namespace" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" # Response: # { # "vectors": [ # { "id": "doc1#chunk1" }, # { "id": "doc1#chunk2" }, # { "id": "doc1#chunk3" }, # { "id": "doc1#chunk4" }, # ... # ], # "pagination": { # "next": "c2Vjb25kY2FsbA==" # }, # "namespace": "example-namespace", # "usage": { # "readUnits": 1 # } # } ``` ## List the IDs of records with a common prefix ID prefixes enable you to query segments of content. Use the `list` endpoint to list all of the records with the common prefix. For more details, see [Use structured IDs](/guides/index-data/data-modeling#use-structured-ids). ## Paginate through results The `list` endpoint returns up to 100 IDs per page at a time by default. If the `limit` parameter is passed, `list` returns up to that number of IDs per page instead. For example, if `limit=3`, up to 3 IDs be returned per page. Whenever there are additional IDs to return, the response also includes a `pagination_token` for fetching the next page of IDs. ### Implicit pagination When using the Python SDK, `list` paginates automatically. ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key='YOUR_API_KEY') # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") for ids in index.list(namespace='example-namespace'): print(ids) # Response: # ['doc1#chunk1', 'doc1#chunk2', 'doc1#chunk3'] # ['doc1#chunk4', 'doc1#chunk5', 'doc1#chunk6'] # ... ``` ### Manual pagination When using the Node.js SDK, Java SDK, Go SDK, or REST API, you must manually fetch each page of results. You can also manually paginate with the Python SDK using `list_paginated()`. ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key='YOUR_API_KEY') # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") namespace = 'example-namespace' # For manual control over pagination results = index.list_paginated( prefix='pref', limit=3, namespace='example-namespace' ) print(results.namespace) print([v.id for v in results.vectors]) print(results.pagination.next) print(results.usage) # Results: # ['10103-0', '10103-1', '10103-10'] # eyJza2lwX3Bhc3QiOiIxMDEwMy0= # {'read_units': 1} ``` ```js JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone(); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace"); const results = await index.listPaginated({ prefix: 'doc1#', limit: 3 }); console.log(results); // Response: // { // vectors: [ // { id: 'doc1#01' }, { id: 'doc1#02' }, { id: 'doc1#03' } // ], // pagination: { // next: 'eyJza2lwX3Bhc3QiOiJwcmVUZXN0LSCIsInByZWZpeCI6InByZVRlc3QifQ==' // }, // namespace: 'example-namespace', // usage: { readUnits: 1 } // } ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.proto.ListResponse; public class ListExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); ListResponse listResponse = index.list("example-namespace", "doc1#" 2); /* Note: You must include an ID prefix to list vector IDs. */ System.out.println(listResponse.getVectorsList()); System.out.println(listResponse.getPagination()); } } // Response: // vectors { // id: "doc1#chunk1" // } // vectors { // id: "doc1#chunk2" // } // pagination { // next: "eyJza2lwX3Bhc3QiOiJhbHN0cm9lbWVyaWEtcGVydXZpYW4iLCJwcmVmaXgiOm51bGx9" // } // namespace: "example-namespace" // usage { // read_units: 1 // } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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/manage-data/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) } limit := uint32(3) res, err := idxConnection.ListVectors(ctx, &pinecone.ListVectorsRequest{ Limit: &limit, }) if len(res.VectorIds) == 0 { fmt.Println("No vectors found") } else { fmt.Printf(prettifyStruct(res)) } } // Response: // { // "vector_ids": [ // "doc1#chunk1", // "doc1#chunk2", // "doc1#chunk3" // ], // "usage": { // "read_units": 1 // }, // "next_pagination_token": "eyJza2lwX3Bhc3QiOiIwMDBkMTc4OC0zMDAxLTQwZmMtYjZjNC0wOWI2N2I5N2JjNDUiLCJwcmVmaXgiOm51bGx9" // } ``` ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/vectors/list?namespace=example-namespace" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" # Response: # { # "vectors": [ # { "id": "doc1#chunk1" }, # { "id": "doc1#chunk2" }, # { "id": "doc1#chunk3" }, # { "id": "doc1#chunk4" }, # ... # ], # "pagination": { # "next": "c2Vjb25kY2FsbA==" # }, # "namespace": "example-namespace", # "usage": { # "readUnits": 1 # } # } ``` Then, to get the next batch of IDs, use the returned `pagination_token`: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key='YOUR_API_KEY') # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") namespace = 'example-namespace' results = index.list_paginated( prefix='pref', limit=3, namespace='example-namespace', pagination_token='eyJza2lwX3Bhc3QiOiIxMDEwMy0=' ) print(results.namespace) print([v.id for v in results.vectors]) print(results.pagination.next) print(results.usage) # Response: # ['10103-0', '10103-1', '10103-10'] # xndlsInByZWZpeCI6IjEwMTAzIn0== # {'read_units': 1} ``` ```js JavaScript theme={null} await index.listPaginated({ prefix: 'doc1#', limit: 3, paginationToken: results.pagination.next}); // Response: // { // vectors: [ // { id: 'doc1#10' }, { id: 'doc1#11' }, { id: 'doc1#12' } // ], // pagination: { // next: 'dfajlkjfdsoijeowjoDJFKLJldLIFf34KFNLDSndaklqoLQJORN45afdlkJ==' // }, // namespace: 'example-namespace', // usage: { readUnits: 1 } // } ``` ```java Java theme={null} listResponse = index.list("example-namespace", "doc1#", "eyJza2lwX3Bhc3QiOiJ2MTg4IiwicHJlZml4IjpudWxsfQ=="); System.out.println(listResponse.getVectorsList()); // Response: // vectors { // id: "doc1#chunk3" // } // vectors { // id: "doc1#chunk4" // } // vectors { // id: "doc1#chunk5" // } // vectors { // id: "doc1#chunk6" // } // vectors { // id: "doc1#chunk7" // } // vectors { // id: "doc1#chunk8" // } // pagination { // next: "eyJza2lwX3Bhc3QiOiJhbHN0cm9lbWVyaWEtcGVydXZpYW4iLCJwcmVmaXgiOm51bGx9" // } // namespace: "example-namespace" // usage { // read_units: 1 // } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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/manage-data/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) } limit := uint32(3) paginationToken := "dfajlkjfdsoijeowjoDJFKLJldLIFf34KFNLDSndaklqoLQJORN45afdlkJ==" res, err := idxConnection.ListVectors(ctx, &pinecone.ListVectorsRequest{ Limit: &limit, PaginationToken: &paginationToken, }) if len(res.VectorIds) == 0 { fmt.Println("No vectors found") } else { fmt.Printf(prettifyStruct(res)) } } // Response: // { // "vector_ids": [ // "doc1#chunk4", // "doc1#chunk5", // "doc1#chunk6" // ], // "usage": { // "read_units": 1 // }, // "next_pagination_token": "eyJza2lwX3Bhc3QiOiIwMDBkMTc4OC0zMDAxLTQwZmMtYjZjNC0wOWI2N2I5N2JjNDUiLCJwcmVmaXgiOm51bGx9" // } ``` ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/vectors/list?namespace=example-namespace&paginationToken=c2Vjb25kY2FsbA%3D%3D" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" # Response: # { # "vectors": [ # { "id": "doc2#chunk1" }, # { "id": "doc2#chunk1" }, # { "id": "doc2#chunk1" }, # { "id": "doc2#chunk1" }, # ... # ], # "pagination": { # "next": "mn23b4jB3Y9jpsS1" # }, # "namespace": "example-namespace", # "usage": { # "readUnits": 1 # } # } ``` When there are no more IDs to return, the response does not includes a `pagination_token`: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key='YOUR_API_KEY') index = pc.Index(host="INDEX_HOST") namespace = 'example-namespace' results = index.list_paginated( prefix='10103', limit=3, pagination_token='xndlsInByZWZpeCI6IjEwMTAzIn0==' ) print(results.namespace) print([v.id for v in results.vectors]) print(results.pagination.next) print(results.usage) # Response: # ['10103-4', '10103-5', '10103-6'] # {'read_units': 1} ``` ```js JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone(); const index = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace"); const results = await index.listPaginated({ prefix: 'doc1#' }); console.log(results); // Response: // { // vectors: [ // { id: 'doc1#19' }, { id: 'doc1#20' }, { id: 'doc1#21' } // ], // namespace: 'example-namespace', // usage: { readUnits: 1 } // } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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) } 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) } limit := uint32(3) paginationToken := "eyJza2lwX3Bhc3QiOiIwMDBkMTc4OC0zMDAxLTQwZmMtYjZjNC0wOWI2N2I5N2JjNDUiLCJwcmVmaXgiOm51bGx9" res, err := idxConnection.ListVectors(ctx, &pinecone.ListVectorsRequest{ Limit: &limit, paginationToken: &paginationToken, }) if len(res.VectorIds) == 0 { fmt.Println("No vectors found") } else { fmt.Printf(prettifyStruct(res)) } } // Response: // { // "vector_ids": [ // "doc1#chunk7", // "doc1#chunk8", // "doc1#chunk9" // ], // "usage": { // "read_units": 1 // } // } ``` ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/vectors/list?namespace=example-namespace&paginationToken=mn23b4jB3Y9jpsS1" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" # Response: # { # "vectors": [ # { "id": "doc3#chunk1" }, # { "id": "doc5#chunk2" }, # { "id": "doc5#chunk3" }, # { "id": "doc5#chunk4" }, # ... # ], # "namespace": "example-namespace", # "usage": { # "readUnits": 1 # } # } ``` # Manage serverless indexes Source: https://docs.pinecone.io/guides/manage-data/manage-indexes List, describe, configure, and delete serverless indexes in Pinecone, including tags, deletion protection, and metadata index configuration. This page shows you how to manage your existing serverless indexes. ## List indexes Use the [`list_indexes`](/reference/api/latest/control-plane/list_indexes) operation to get a complete description of all indexes in a project: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index_list = pc.list_indexes() print(index_list) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) const indexList = await pc.listIndexes(); console.log(indexList); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class ListIndexesExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); IndexList indexList = pc.listIndexes(); System.out.println(indexList); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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) } idxs, err := pc.ListIndexes(ctx) if err != nil { log.Fatalf("Failed to list indexes: %v", err) } else { for _, index := range idxs { fmt.Printf("index: %v\n", prettifyStruct(index)) } } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/indexes" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` The response will look like this: ```python Python theme={null} [{ "name": "docs-example-sparse", "metric": "dotproduct", "host": "docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "vector_type": "sparse", "dimension": null, "deletion_protection": "disabled", "tags": { "environment": "development" } }, { "name": "docs-example-dense", "metric": "cosine", "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "vector_type": "dense", "dimension": 1536, "deletion_protection": "disabled", "tags": { "environment": "development" } }] ``` ```javascript JavaScript theme={null} { indexes: [ { name: 'docs-example-sparse', dimension: undefined, metric: 'dotproduct', host: 'docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io', deletionProtection: 'disabled', tags: { environment: 'development', example: 'tag' }, embed: undefined, spec: { pod: undefined, serverless: { cloud: 'aws', region: 'us-east-1' } }, status: { ready: true, state: 'Ready' }, vectorType: 'sparse' }, { name: 'docs-example-dense', dimension: 1536, metric: 'cosine', host: 'docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io', deletionProtection: 'disabled', tags: { environment: 'development', example: 'tag' }, embed: undefined, spec: { pod: undefined, serverless: { cloud: 'aws', region: 'us-east-1' } }, status: { ready: true, state: 'Ready' }, vectorType: 'dense' } ] } ``` ```java Java theme={null} class IndexList { indexes: [class IndexModel { name: docs-example-sparse dimension: null metric: dotproduct host: docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io deletionProtection: disabled tags: {environment=development} embed: null spec: class IndexModelSpec { pod: null serverless: class ServerlessSpec { cloud: aws region: us-east-1 additionalProperties: null } additionalProperties: null } status: class IndexModelStatus { ready: true state: Ready additionalProperties: null } vectorType: sparse additionalProperties: null }, class IndexModel { name: docs-example-dense dimension: 1536 metric: cosine host: docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io deletionProtection: disabled tags: {environment=development} embed: null spec: class IndexModelSpec { pod: null serverless: class ServerlessSpec { cloud: aws region: us-east-1 additionalProperties: null } additionalProperties: null } status: class IndexModelStatus { ready: true state: Ready additionalProperties: null } vectorType: dense additionalProperties: null }] additionalProperties: null } ``` ```go Go theme={null} index: { "name": "docs-example-sparse", "host": "docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io", "metric": "dotproduct", "vector_type": "sparse", "deletion_protection": "disabled", "dimension": null, "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "tags": { "environment": "development" } } index: { "name": "docs-example-dense", "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io", "metric": "cosine", "vector_type": "dense", "deletion_protection": "disabled", "dimension": 1536, "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "tags": { "environment": "development" } } ``` ```json curl theme={null} { "indexes": [ { "name": "docs-example-sparse", "vector_type": "sparse", "metric": "dotproduct", "dimension": null, "status": { "ready": true, "state": "Ready" }, "host": "docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws" } }, "deletion_protection": "disabled", "tags": { "environment": "development" } }, { "name": "docs-example-dense", "vector_type": "dense", "metric": "cosine", "dimension": 1536, "status": { "ready": true, "state": "Ready" }, "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws" } }, "deletion_protection": "disabled", "tags": { "environment": "development" } } ] } ``` With the Python SDK, you can use the `.names()` helper function to iterate over the index names in the `list_indexes()` response, for example: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec for index_name in pc.list_indexes().names: print(index_name) ``` ## Describe an index Use the [`describe_index`](/reference/api/latest/control-plane/describe_index/) endpoint to get a complete description of a specific index: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.describe_index(name="docs-example") ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.describeIndex('docs-example'); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class DescribeIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOURE_API_KEY").build(); IndexModel indexModel = pc.describeIndex("docs-example"); System.out.println(indexModel); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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) } idx, err := pc.DescribeIndex(ctx, "docs-example") if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err) } else { fmt.Printf("index: %v\n", prettifyStruct(idx)) } } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/indexes/docs-example" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` The response will look like this: ```Python Python theme={null} {'deletion_protection': 'disabled', 'dimension': 1536, 'host': 'docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io', 'metric': 'cosine', 'name': 'docs-example-dense', 'spec': {'serverless': {'cloud': 'aws', 'region': 'us-east-1'}}, 'status': {'ready': True, 'state': 'Ready'}, 'tags': {'environment': 'development'}, 'vector_type': 'dense'} ``` ```javaScript JavaScript theme={null} { name: 'docs-example-dense', dimension: 1536, metric: 'cosine', host: 'docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io', deletionProtection: 'disabled', tags: { environment: 'development', example: 'tag' }, embed: undefined, spec: { pod: undefined, serverless: { cloud: 'aws', region: 'us-east-1' } }, status: { ready: true, state: 'Ready' }, vectorType: 'dense' } ``` ```java Java theme={null} class IndexModel { name: docs-example-dense dimension: 1536 metric: cosine host: docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io deletionProtection: disabled tags: {environment=development} embed: null spec: class IndexModelSpec { pod: null serverless: class ServerlessSpec { cloud: aws region: us-east-1 additionalProperties: null } additionalProperties: null } status: class IndexModelStatus { ready: true state: Ready additionalProperties: null } vectorType: dense additionalProperties: null } ``` ```go Go theme={null} index: { "name": "docs-example-dense", "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io", "metric": "cosine", "vector_type": "dense", "deletion_protection": "disabled", "dimension": 1536, "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "tags": { "environment": "development" } } ``` ```json curl theme={null} { "name": "docs-example-dense", "vector_type": "dense", "metric": "cosine", "dimension": 1536, "status": { "ready": true, "state": "Ready" }, "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws" } }, "deletion_protection": "disabled", "tags": { "environment": "development" } } ``` **Do not target an index by name in production.** When you target an index by name for data operations such as `upsert` and `query`, the SDK gets the unique DNS host for the index using the `describe_index` operation. This is convenient for testing but should be avoided in production because `describe_index` uses a different API than data operations and therefore adds an additional network call and point of failure. Instead, you should get an index host once and cache it for reuse or specify the host directly. ## Delete an index Use the [`delete_index`](reference/api/latest/control-plane/delete_index) operation to delete an index and all of its associated resources. ```python Python theme={null} # pip install "pinecone[grpc]" from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.delete_index(name="docs-example") ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.deleteIndex('docs-example'); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; public class DeleteIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.deleteIndex("docs-example"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } indexName := "docs-example" err = pc.DeleteIndex(ctx, indexName) if err != nil { log.Fatalf("Failed to delete index: %v", err) } else { fmt.Println("Index \"%v\" deleted successfully", indexName) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X DELETE "https://api.pinecone.io/indexes/docs-example" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` If deletion protection is enabled on an index, requests to delete it will fail and return a `403 - FORBIDDEN` status with the following error: ``` Deletion protection is enabled for this index. Disable deletion protection before retrying. ``` Before you can delete such an index, you must first [disable deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection). You can delete an index using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes). For the index you want to delete, click the three dots to the right of the index name, then click **Delete**. ## Associate an embedding model [Integrated inference](/guides/index-data/indexing-overview#integrated-embedding) lets you upsert and search without extra steps for embedding data and reranking results. To configure an existing serverless index for an embedding model, use the [`configure_index`](/reference/api/latest/control-plane/configure_index) operation as follows: * Set `embed.model` to one of [Pinecone's hosted embedding models](/guides/index-data/create-an-index#embedding-models). * Set `embed.field_map` to the name of the field in your source document that contains the data for embedding. The `vector_type`, `metric`, and `dimension` of the index must be supported by the specified embedding model. ```python Python theme={null} # pip install --upgrade pinecone from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.configure_index( name="docs-example", embed={ "model":"llama-text-embed-v2", "field_map":{"text": "chunk_text"} } ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.configureIndex('docs-example', { embed: { model: 'llama-text-embed-v2', fieldMap: { text: 'chunk_text' }, }, }); ``` ```json curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "embed": { "model": "llama-text-embed-v2", "field_map": { "text": "chunk_text" } } }' ``` ## Configure deletion protection This feature requires [Pinecone API version](/reference/api/versioning) `2024-07`, [Python SDK](/reference/sdks/python/overview) v5.0.0, [Node.js SDK](/reference/sdks/node/overview) v3.0.0, [Java SDK](/reference/sdks/java/overview) v2.0.0, or [Go SDK](/reference/sdks/go/overview) v1.0.0 or later. ### Enable deletion protection You can prevent an index and its data from accidental deleting when [creating a new index](/guides/index-data/create-an-index) or after its been created. In both cases, you set the `deletion_protection` parameter to `enabled`. Enabling deletion protection does *not* prevent [namespace deletions](/guides/manage-data/manage-namespaces#delete-a-namespace). To enable deletion protection when creating a new index: ```python Python theme={null} # pip install "pinecone[grpc]" # Serverless index from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ), deletion_protection="enabled" ) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone // Serverles index import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createIndex({ name: 'docs-example', dimension: 1536, metric: 'cosine', spec: { serverless: { cloud: 'aws', region: 'us-east-1' } }, deletionProtection: 'enabled', }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.IndexModel; import org.openapitools.db_control.client.model.DeletionProtection; // Serverless index public class CreateServerlessIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.createServerlessIndex("docs-example", "cosine", 1536, "aws", "us-east-1", DeletionProtection.enabled); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } // Serverless index indexName := "docs-example" vectorType := "dense" dimension := int32(1536) metric := pinecone.Cosine deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: indexName, VectorType: &vectorType, Dimension: &dimension, Metric: &metric, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: &deletionProtection, Tags: &pinecone.IndexTags{ "environment": "development" }, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", err) } else { fmt.Printf("Successfully created serverless index: %v", idx.Name) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" # Serverless index curl -s "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "deletion_protection": "enabled" }' ``` To enable deletion protection when configuring an existing index: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.configure_index( name="docs-example", deletion_protection="enabled" ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const client = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await client.configureIndex('docs-example', { deletionProtection: 'enabled' }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class ConfigureIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.configureServerlessIndex("docs-example", DeletionProtection.ENABLED); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } idx, err := pc.ConfigureIndex(ctx, "docs-example", pinecone.ConfigureIndexParams{DeletionProtection: "enabled"}) if err != nil { log.Fatalf("Failed to configure index \"%v\": %v", idx.Name, err) } else { fmt.Printf("Successfully configured index \"%v\"", idx.Name) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example-curl" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "deletion_protection": "enabled" }' ``` When deletion protection is enabled on an index, requests to delete the index fail and return a `403 - FORBIDDEN` status with the following error: ``` Deletion protection is enabled for this index. Disable deletion protection before retrying. ``` ### Disable deletion protection Before you can [delete an index](#delete-an-index) with deletion protection enabled, you must first disable deletion protection as follows: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.configure_index( name="docs-example", deletion_protection="disabled" ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const client = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await client.configureIndex('docs-example', { deletionProtection: 'disabled' }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class ConfigureIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.configureServerlessIndex("docs-example", DeletionProtection.DISABLED); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } idx, err := pc.ConfigureIndex(ctx, "docs-example", pinecone.ConfigureIndexParams{DeletionProtection: "disabled"}) if err != nil { log.Fatalf("Failed to configure index \"%v\": %v", idx.Name, err) } else { fmt.Printf("Successfully configured index \"%v\"", idx.Name) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example-curl" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "deletion_protection": "disabled" }' ``` ## Configure index tags Tags are key-value pairs that you can use to categorize and identify the index. ### Add tags To add tags to an index, use the `tags` parameter when [creating a new index](/guides/index-data/create-an-index) or configuring an existing index. To add tags when creating a new index: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ), deletion_protection="disabled", tags={ "example": "tag", "environment": "development" } ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const client = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createIndex({ name: 'docs-example', dimension: 1536, metric: 'cosine', spec: { serverless: { cloud: 'aws', region: 'us-east-1' } }, deletionProtection: 'disabled', tags: { example: 'tag', environment: 'development' }, }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.IndexModel; import org.openapitools.db_control.client.model.DeletionProtection; import java.util.HashMap; // Serverless index public class CreateServerlessIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); HashMap tags = new HashMap<>(); tags.put("tag", "development"); pc.createServerlessIndex("docs-example", "cosine", 1536, "aws", "us-east-1", DeletionProtection.DISABLED, tags); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } // Serverless index idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: "docs-example", Dimension: 1536, Metric: pinecone.Cosine, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: "disabled", Tags: &pinecone.IndexTags{ "example": "tag", "environment": "development" }, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", err) } else { fmt.Printf("Successfully created serverless index: %v", idx.Name) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" # Serverless index curl -s "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "tags": { "example": "tag", "environment": "development" }, "deletion_protection": "disabled" }' ``` You can add tags during index creation using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/create-index/). To add or update tags when configuring an existing index: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.configure_index( name="docs-example", tags={ example: "tag", environment: "development" } ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const client = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await client.configureIndex('docs-example', { tags: { example: 'tag', environment: 'development' }}); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; import java.util.HashMap; public class ConfigureIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); HashMap tags = new HashMap<>(); tags.put("tag", "development"); pc.configureServerlessIndex("docs-example", DeletionProtection.ENABLED, tags); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } idx, err := pc.ConfigureIndex(ctx, "docs-example", pinecone.ConfigureIndexParams{ Tags: pinecone.IndexTags{ "example": "tag", "environment": "development", }, }, ) if err != nil { log.Fatalf("Failed to configure index \"%v\": %v", idx.Name, err) } else { fmt.Printf("Successfully configured index \"%v\"", idx.Name) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example-curl" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "tags": { "example": "tag", "environment": "development" } }' ``` You can add or update tags when configuring an existing index using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes). Find the index to edit and click the **ellipsis (...) menu > Add tags**. ### View tags To view the tags of an index, [list all indexes](/guides/manage-data/manage-indexes) in a project or [get information about a specific index](/guides/manage-data/manage-indexes). ### Remove tags To remove a tag from an index, [configure the index](/reference/api/latest/control-plane/configure_index) and use the `tags` parameter to send the tag key with an empty value (`""`). The following example removes the `example: tag` tag from `docs-example`: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.configure_index( name="docs-example", tags={"example": ""} ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const client = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await client.configureIndex('docs-example', { tags: { example: '' }}); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; import java.util.HashMap; public class ConfigureIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); HashMap tags = new HashMap<>(); tags.put("example", ""); pc.configureServerlessIndex("docs-example", DeletionProtection.ENABLED, tags); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } idx, err := pc.ConfigureIndex(ctx, "docs-example", pinecone.ConfigureIndexParams{ Tags: pinecone.IndexTags{ "example": "", }, }, ) if err != nil { log.Fatalf("Failed to configure index \"%v\": %v", idx.Name, err) } else { fmt.Printf("Successfully configured index \"%v\"", idx.Name) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example-curl" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "tags": { "example": "" } }' ``` You can remove tags from an index using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes). Find the index to edit and click the **ellipsis (...) menu > \_\_ tags**. ## List backups for an index Serverless indexes can be [backed up](/guides/manage-data/back-up-an-index). You can [list all backups for a specific index](/reference/api/latest/control-plane/list_index_backups), as in the following example: ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index_backups = pc.list_backups(index_name="docs-example") print(index_backups) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) const indexBackups = await pc.listBackups({ indexName: 'docs-example' }); console.log(indexBackups); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.ApiException; import org.openapitools.db_control.client.model.*; public class CreateBackup { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); String indexName = "docs-example"; BackupList indexBackupList = pc.listIndexBackups(indexName); System.out.println(indexBackupList); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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) } indexName := "docs-example" limit := 2 indexBackups, err := pc.ListBackups(ctx, &pinecone.ListBackupsParams{ Limit: &limit, IndexName: &indexName, }) if err != nil { log.Fatalf("Failed to list backups: %v", err) } fmt.Printf(prettifyStruct(indexBackups)) } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="docs-example" curl -X GET "https://api.pinecone.io/indexes/$INDEX_NAME/backups" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "accept: application/json" ``` The example returns a response like the following: ```python Python theme={null} [{ "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "source_index_name": "docs-example", "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "status": "Ready", "cloud": "aws", "region": "us-east-1", "tags": {}, "name": "example-backup", "description": "Monthly backup of production index", "dimension": 1024, "record_count": 98, "namespace_count": 3, "size_bytes": 1069169, "created_at": "2025-05-15T00:52:10.809305882Z" }] ``` ```javascript JavaScript theme={null} { data: [ { backupId: '8c85e612-ed1c-4f97-9f8c-8194e07bcf71', sourceIndexName: 'docs-example', sourceIndexId: 'f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74', name: 'example-backup', description: 'Monthly backup of production index', status: 'Ready', cloud: 'aws', region: 'us-east-1', dimension: 1024, metric: undefined, recordCount: 98, namespaceCount: 3, sizeBytes: 1069169, tags: {}, createdAt: '2025-05-14T16:37:25.625540Z' } ], pagination: undefined } ``` ```java Java theme={null} class BackupList { data: [class BackupModel { backupId: 8c85e612-ed1c-4f97-9f8c-8194e07bcf71 sourceIndexName: docs-example sourceIndexId: f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74 name: example-backup description: Monthly backup of production index status: Initializing cloud: aws region: us-east-1 dimension: null metric: null recordCount: null namespaceCount: null sizeBytes: null tags: {} createdAt: 2025-05-16T19:46:26.248428Z additionalProperties: null }] pagination: null additionalProperties: null } ``` ```go Go theme={null} { "data": [ { "backup_id": "bf2cda5d-b233-4a0a-aae9-b592780ad3ff", "cloud": "aws", "created_at": "2025-05-16T18:01:51.531129Z", "description": "Monthly backup of production index", "dimension": 0, "name": "example-backup", "namespace_count": 1, "record_count": 96, "region": "us-east-1", "size_bytes": 86393, "source_index_id": "bcb5b3c9-903e-4cb6-8b37-a6072aeb874f", "source_index_name": "docs-example", "status": "Ready", "tags": {} }, { "backup_id": "e12269b0-a29b-4af0-9729-c7771dec03e3", "cloud": "aws", "created_at": "2025-05-14T17:00:45.803146Z", "dimension": 0, "name": "example-backup2", "namespace_count": 1, "record_count": 96, "region": "us-east-1", "size_bytes": 86393, "source_index_id": "bcb5b3c9-903e-4cb6-8b37-a6072aeb874f", "source_index_name": "docs-example", "status": "Ready" } ], "pagination": { "next": "eyJsaW1pdCI6Miwib2Zmc2V0IjoyfQ==" } } ``` ```json curl theme={null} { "data": [ { "backup_id":"9947520e-d5a1-4418-a78d-9f464c9969da", "source_index_id":"8433941a-dae7-43b5-ac2c-d3dab4a56b2b", "source_index_name":"docs-example", "tags":{}, "name":"example-backup", "description":"Monthly backup of production index", "status":"Pending", "cloud":"aws", "region":"us-east-1", "dimension":1024, "record_count":98, "namespace_count":3, "size_bytes":1069169, "created_at":"2025-03-11T18:29:50.549505Z" } ], "pagination":null } ``` You can view the backups for a specific index from either the [Backups](https://app.pinecone.io/organizations/-/projects/-/backups) tab or the [Indexes](https://app.pinecone.io/organizations/-/projects/-/indexes) tab in the Pinecone console. # Manage namespaces Source: https://docs.pinecone.io/guides/manage-data/manage-namespaces Create, describe, list, and delete namespaces in Pinecone serverless indexes, including defining filterable metadata fields and schemas ahead of upsert. ## Create a namespace This feature is available only on the `2025-10` version of the API. Namespaces are created automatically as you [upsert](/guides/index-data/upsert-data) records. However, you can also create namespaces ahead of time using the [`create_namespace`](/reference/api/2025-10/data-plane/createnamespace) operation. Specify a name for the namespace and, optionally, the [metadata fields to index](/guides/index-data/create-an-index#metadata-indexing). ```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/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") namespace = index.create_namespace( name="example-namespace", schema={ "fields": { "document_id": {"filterable": True}, "document_title": {"filterable": True}, "chunk_number": {"filterable": True}, "document_url": {"filterable": True}, "created_at": {"filterable": True} } } ) print(namespace) ``` ```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/manage-data/target-an-index const index = pc.index('INDEX_NAME', 'INDEX_HOST'); const namespace = await index.createNamespace({ name: 'example-namespace', schema: { fields: { document_id: { filterable: true }, document_title: { filterable: true }, chunk_number: { filterable: true }, document_url: { filterable: true }, created_at: { filterable: true } } } }); console.log(namespace); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.proto.NamespaceDescription; import io.pinecone.proto.MetadataSchema; import io.pinecone.proto.MetadataSchemaField; public class CreateNamespaceExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "INDEX_NAME"); MetadataSchemaField filterable = MetadataSchemaField.newBuilder() .setFilterable(true) .build(); MetadataSchema schema = MetadataSchema.newBuilder() .putFields("document_id", filterable) .putFields("document_title", filterable) .putFields("chunk_number", filterable) .putFields("document_url", filterable) .putFields("created_at", filterable) .build(); NamespaceDescription namespace = index.createNamespace("example-namespace", schema); System.out.println(namespace); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } namespace, err := idxConnection.CreateNamespace(ctx, &pinecone.CreateNamespaceParams{ Name: "example-namespace", Schema: &pinecone.MetadataSchema{ Fields: map[string]pinecone.MetadataSchemaField{ "document_id": {Filterable: true}, "document_title": {Filterable: true}, "chunk_number": {Filterable: true}, "document_url": {Filterable: true}, "created_at": {Filterable: true}, }, }, }) if err != nil { log.Fatalf("Failed to create namespace: %v", err) } fmt.Printf(prettifyStruct(namespace)) } ``` ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/namespaces" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "example-namespace", "schema": { "fields": { "document_id": {"filterable": true}, "document_title": {"filterable": true}, "chunk_number": {"filterable": true}, "document_url": {"filterable": true}, "created_at": {"filterable": true} } } }' ``` The response will look like the following: ```json theme={null} { "name": "example-namespace", "record_count": "0", "schema": { "fields": { "document_title": { "filterable": true }, "document_url": { "filterable": true }, "chunk_number": { "filterable": true }, "document_id": { "filterable": true }, "created_at": { "filterable": true } } } } ``` ## List all namespaces in an index Use the [`list_namespaces`](/reference/api/latest/data-plane/listnamespaces) operation to list all namespaces in a serverless index. Up to 100 namespaces are returned at a time by default, in sorted order (bitwise “C” collation). If the `limit` parameter is set, up to that number of namespaces are returned instead. Whenever there are additional namespaces to return, the response also includes a `pagination_token` that you can use to get the next batch of namespaces. When the response does not include a `pagination_token`, there are no more namespaces to return. ```python Python theme={null} # Not supported with pinecone["grpc"] extras installed from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index(host="INDEX_HOST") # Implicit pagination using a generator function for namespace in index.list_namespaces(): print(namespace.name, ":", namespace.record_count) # Manual pagination namespaces = index.list_namespaces_paginated( limit=2, pagination_token="eyJza2lwX3Bhc3QiOiIxMDEwMy0=" ) print(namespaces) ``` ```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/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); const namespaceList = await index.listNamespaces(); console.log(namespaceList); ``` ```java Java theme={null} import io.pinecone.clients.AsyncIndex; import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.proto.ListNamespacesResponse; import org.openapitools.db_data.client.ApiException; public class Namespaces { public static void main(String[] args) throws ApiException { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "docs-example"); // List all namespaces with default pagination limit (100) ListNamespacesResponse listNamespacesResponse = index.listNamespaces(null, null); // List all namespaces with pagination limit of 2 ListNamespacesResponse listNamespacesResponseWithLimit = index.listNamespaces(2); // List all namespaces with pagination limit and token ListNamespacesResponse listNamespacesResponsePaginated = index.listNamespaces(5, "eyJza2lwX3Bhc3QiOiIxMDEwMy0="); System.out.println(listNamespacesResponseWithLimit); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } limit := uint32(10) namespaces, err := idxConnection.ListNamespaces(ctx, &pinecone.ListNamespacesParams{ Limit: &limit, }) if err != nil { log.Fatalf("Failed to list namespaces: %v", err) } fmt.Printf(prettifyStruct(namespaces)) } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/namespaces" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` The response will look like the following: ```plaintext Python theme={null} # Implicit pagination (print output from: for n in index.list_namespaces(): print(n.name, ":", n.record_count)) example-namespace : 20000 example-namespace2 : 10500 example-namespace3 : 10000 ... # Manual pagination (response from list_namespaces_paginated()) { "namespaces": [ {"name": "example-namespace", "record_count": "20000"}, {"name": "example-namespace2", "record_count": "10500"} ], "pagination": {"next": "Tm90aGluZyB0byBzZWUgaGVyZQo="} } ``` ```javascript JavaScript theme={null} { namespaces: [ { name: 'example-namespace', recordCount: '20000' }, { name: 'example-namespace2', recordCount: '10500' }, ... ], pagination: "Tm90aGluZyB0byBzZWUgaGVyZQo=" } ``` ```java Java theme={null} namespaces { name: "example-namespace" record_count: 20000 } namespaces { name: "example-namespace2" record_count: 10500 } pagination { next: "eyJza2lwX3Bhc3QiOiJlZDVhYzFiNi1kMDFiLTQ2NTgtYWVhZS1hYjJkMGI2YzBiZjQiLCJwcmVmaXgiOm51bGx9" } ``` ```go Go theme={null} { "Namespaces": [ { "name": "example-namespace", "record_count": 20000 }, { "name": "example-namespace2", "record_count": 10500 }, ... ], "Pagination": { "next": "eyJza2lwX3Bhc3QiOiIyNzQ5YTU1YS0zZTQ2LTQ4MDItOGFlNi1hZTJjZGNkMTE5N2IiLCJwcmVmaXgiOm51bGx9" } } ``` ```json curl theme={null} { "namespaces": [ { "name": "example-namespace", "record_count": 20000 }, { "name": "example-namespace2", "record_count": 10500 }, ... ], "pagination": { "next": "Tm90aGluZyB0byBzZWUgaGVyZQo=" } } ``` ## Describe a namespace Use the [`describe_namespace`](/reference/api/latest/data-plane/describenamespace) operation to get details about a namespace in a serverless index, including the total number of vectors in the namespace. ```python Python theme={null} # Not supported with pinecone["grpc"] extras installed from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index(host="INDEX_HOST") namespace = index.describe_namespace(namespace="example-namespace") print(namespace) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) const index = pc.index('docs-example'); const namespace = await index.describeNamespace('example-namespace'); console.log(namespace); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.proto.NamespaceDescription; import org.openapitools.db_data.client.ApiException; public class Namespaces { public static void main(String[] args) throws ApiException { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "docs-example"); NamespaceDescription namespaceDescription = index.describeNamespace("example-namespace"); System.out.println(namespaceDescription); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } namespace, err := idxConnection.DescribeNamespace(ctx, "example-namespace") if err != nil { log.Fatalf("Failed to describe namespace: %v", err) } fmt.Printf(prettifyStruct(namespace)) } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" NAMESPACE="NAMESPACE_NAME" # To target the default namespace, use "__default__". curl -X GET "https://$INDEX_HOST/namespaces/$NAMESPACE" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` The response will look like the following: ```python Python theme={null} { "name": "example-namespace", "record_count": "20000" } ``` ```javascript JavaScript theme={null} { name: 'example-namespace', recordCount: '20000' } ``` ```java Java theme={null} name: "example-namespace" record_count: 20000 ``` ```go Go theme={null} { "name": "example-namespace", "record_count": 20000 } ``` ```json curl theme={null} { "name": "example-namespace", "record_count": 20000 } ``` ## Delete a namespace Use the [`delete_namespace`](/reference/api/latest/data-plane/deletenamespace) operation to delete a namespace in a serverless index. Deleting a namespace is irreversible. All data in the namespace is permanently deleted. ```python Python theme={null} # Not supported with pinecone["grpc"] extras installed from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index(host="INDEX_HOST") index.delete_namespace(namespace="example-namespace") ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) const index = pc.index('INDEX_NAME', 'INDEX_HOST'); const namespace = await index.deleteNamespace('example-namespace'); console.log(namespace); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import java.util.concurrent.ExecutionException; public class DeleteNamespace { public static void main(String[] args) throws ExecutionException, InterruptedException { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "docs-example"); index.deleteNamespace("example-namespace"); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } err := idxConnection.DeleteNamespace(ctx, "example-namespace") if err != nil { log.Fatalf("Failed to delete namespace: %v", err) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" NAMESPACE="NAMESPACE_NAME" # To target the default namespace, use "__default__". curl -X DELETE "https://$INDEX_HOST/namespaces/$NAMESPACE" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ## Rename a namespace Pinecone does not support renaming namespaces directly. Instead, you must [delete the records](/guides/manage-data/delete-data) in the namespace and [upsert the records](/guides/index-data/upsert-data) to a new namespace. ## Move records to a new namespace Pinecone does not support moving records between namespaces directly. Instead, you must [delete the records](/guides/manage-data/delete-data) in the old namespace and [upsert the records](/guides/index-data/upsert-data) to the new namespace. # Restore an index Source: https://docs.pinecone.io/guides/manage-data/restore-an-index Restore a Pinecone serverless index from a backup, change the index name, tags, or deletion protection, and preserve embedding model configuration. ## Create a serverless index from a backup When restoring a serverless index from backup, you can change the index name, tags, and deletion protection setting. All other properties of the restored index will remain identical to the source index, including cloud and region by default, dimension and similarity metric, and associated embedding model when restoring an index with [integrated embedding](/guides/index-data/indexing-overview#integrated-embedding). To restore a backup into a different region than the source index, see [Restore to a different region](#restore-to-a-different-region). To [create a serverless index from a backup](/reference/api/latest/control-plane/create_index_from_backup), provide the ID of the backup, the name of the new index, and, optionally, changes to the index tags and deletion protection settings: ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index_from_backup( backup_id="a65ff585-d987-4da5-a622-72e19a6ed5f4", name="restored-index", tags={ "tag0": "val0", "tag1": "val1" }, deletion_protection="enabled" ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) const response = await pc.createIndexFromBackup({ backupId: 'a65ff585-d987-4da5-a622-72e19a6ed5f4', name: 'restored-index', tags: { tag0: 'val0', tag1: 'val1' }, deletionProtection: 'enabled' }); console.log(response); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.ApiException; import org.openapitools.db_control.client.model.*; public class CreateIndexFromBackup { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); String backupID = "a65ff585-d987-4da5-a622-72e19a6ed5f4"; String indexName = "restored-index"; CreateIndexFromBackupResponse backupResponse = pc.createIndexFromBackup(backupID, indexName); System.out.println(backupResponse); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "time" "github.com/pinecone-io/go-pinecone/v4/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) } indexName := "restored-index" restoredIndexTags := pinecone.IndexTags{"restored_on": time.Now().Format("2006-01-02 15:04")} createIndexFromBackupResp, err := pc.CreateIndexFromBackup(ctx, &pinecone.CreateIndexFromBackupParams{ BackupId: "e12269b0-a29b-4af0-9729-c7771dec03e3", Name: indexName, Tags: &restoredIndexTags, }) fmt.Printf(prettifyStruct(createIndexFromBackupResp)) } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" BACKUP_ID="a65ff585-d987-4da5-a622-72e19a6ed5f4" curl "https://api.pinecone.io/backups/$BACKUP_ID/create-index" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H 'Content-Type: application/json' \ -d '{ "name": "restored-index", "tags": { "tag0": "val0", "tag1": "val1" }, "deletion_protection": "enabled" }' ``` The example returns a response like the following: ```python Python theme={null} {'deletion_protection': 'enabled', 'dimension': 1024, 'embed': {'dimension': 1024, 'field_map': {'text': 'chunk_text'}, 'metric': 'cosine', 'model': 'multilingual-e5-large', 'read_parameters': {'input_type': 'query', 'truncate': 'END'}, 'vector_type': 'dense', 'write_parameters': {'input_type': 'passage', 'truncate': 'END'}}, 'host': 'example-dense-index-python3-govk0nt.svc.aped-4627-b74a.pinecone.io', 'metric': 'cosine', 'name': 'example-dense-index-python3', 'spec': {'serverless': {'cloud': 'aws', 'region': 'us-east-1'}}, 'status': {'ready': True, 'state': 'Ready'}, 'tags': {'tag0': 'val0', 'tag1': 'val1'}, 'vector_type': 'dense'} ``` ```javascript JavaScript theme={null} { restoreJobId: 'e9ba8ff8-7948-4cfa-ba43-34227f6d30d4', indexId: '025117b3-e683-423c-b2d1-6d30fbe5027f' } ``` ```java Java theme={null} class CreateIndexFromBackupResponse { restoreJobId: e9ba8ff8-7948-4cfa-ba43-34227f6d30d4 indexId: 025117b3-e683-423c-b2d1-6d30fbe5027f additionalProperties: null } ``` ```go Go theme={null} { "index_id": "025117b3-e683-423c-b2d1-6d30fbe5027f", "restore_job_id": "e9ba8ff8-7948-4cfa-ba43-34227f6d30d4" } ``` ```json curl theme={null} { "restore_job_id":"e9ba8ff8-7948-4cfa-ba43-34227f6d30d4", "index_id":"025117b3-e683-423c-b2d1-6d30fbe5027f" } ``` You can create a serverless index from a backup using the [Pinecone console](https://app.pinecone.io/organizations/-/projects). ## Restore to a different region The [create index from backup](/reference/api/latest/control-plane/create_index_from_backup) endpoint always creates the new index in the same cloud and region as the backup. To restore a backup into a different region, use the `unstable` version of the [create index](/reference/api/latest/control-plane/create_index) endpoint instead. Specify the backup as `source_backup_id` within `spec.serverless` and set the target `region` there. The following rules apply: * The target region must be on the same cloud provider as the backup. Restoring to a different cloud provider is not supported. * The backup must be in the current Pinecone project, and the new index is created in the same project. * The `dimension`, `metric`, and `vector_type` must match the source index. * Restoring to a different region is not supported for BYOC indexes. Restoring to a different region is in [public preview](/release-notes/feature-availability). It is available through the `unstable` API version and the REST API only. For example, the following request restores a backup of a dense index hosted in the AWS `us-east-1` region into a new index in the AWS `us-west-2` region: ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl "https://api.pinecone.io/indexes" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: unstable" \ -d '{ "name": "restored-index", "vector_type": "dense", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud": "aws", "region": "us-west-2", "source_backup_id": "a65ff585-d987-4da5-a622-72e19a6ed5f4" } } }' ``` Because the backup data is copied between regions, restoring to a different region can take longer than restoring within the same region. If restoring to a different region is not yet available for the backup's region, the request fails with a `412 Precondition Failed` error. ## List restore jobs You can [list all restore jobs](/reference/api/latest/control-plane/list_restore_jobs) as follows. Up to 100 restore jobs are returned at a time by default, in sorted order (bitwise “C” collation). If the `limit` parameter is set, up to that number of restore jobs are returned instead. Whenever there are additional restore jobs to return, the response also includes a `pagination_token` that you can use to get the next batch of jobs. When the response does not include a `pagination_token`, there are no more restore jobs to return. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") restore_jobs = pc.list_restore_jobs() print(restore_jobs) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) const restoreJobs = await pc.listRestoreJobs(); console.log(restoreJobs); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.ApiException; import org.openapitools.db_control.client.model.*; public class CreateIndexFromBackup { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API-KEY").build(); // List all restore jobs with default pagination limit RestoreJobList restoreJobList = pc.listRestoreJobs(null, null); // List all restore jobs with pagination limit of 5 RestoreJobList restoreJobListWithLimit = pc.listRestoreJobs(5); // List all restore jobs with pagination limit and token RestoreJobList restoreJobListPaginated = pc.listRestoreJobs(5, "eyJza2lwX3Bhc3QiOiIxMDEwMy0="); System.out.println(restoreJobList); System.out.println(restoreJobListWithLimit); System.out.println(restoreJobListPaginated); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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) } limit := 2 restoreJobs, err := pc.ListRestoreJobs(ctx, &pinecone.ListRestoreJobsParams{ Limit: &limit, }) if err != nil { log.Fatalf("Failed to list restore jobs: %v", err) } fmt.Printf(prettifyStruct(restoreJobs)) } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl "https://api.pinecone.io/restore-jobs" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Api-Key: $PINECONE_API_KEY" ``` The example returns a response like the following: ```python Python theme={null} [{ "restore_job_id": "06b08366-a0a9-404d-96c2-e791c71743e5", "backup_id": "95707edb-e482-49cf-b5a5-312219a51a97", "target_index_name": "restored-index", "target_index_id": "027aff93-de40-4f48-a573-6dbcd654f961", "status": "Completed", "created_at": "2025-05-15T13:59:51.439479+00:00", "completed_at": "2025-05-15T14:00:09.222998+00:00", "percent_complete": 100.0 }, { "restore_job_id": "4902f735-b876-4e53-a05c-bc01d99251cb", "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "target_index_name": "restored-index2", "target_index_id": "027aff93-de40-4f48-a573-6dbcd654f961", "status": "Completed", "created_at": "2025-05-15T21:06:19.906074+00:00", "completed_at": "2025-05-15T21:06:39.360509+00:00", "percent_complete": 100.0 }] ``` ```javascript JavaScript theme={null} { data: [ { restoreJobId: '69acc1d0-9105-4fcb-b1db-ebf97b285c5e', backupId: '8c85e612-ed1c-4f97-9f8c-8194e07bcf71', targetIndexName: 'restored-index2', targetIndexId: 'e6c0387f-33db-4227-9e91-32181106e56b', status: 'Completed', createdAt: 2025-05-14T17:25:59.378Z, completedAt: 2025-05-14T17:26:23.997Z, percentComplete: 100 }, { restoreJobId: '9857add2-99d4-4399-870e-aa7f15d8d326', backupId: '94a63aeb-efae-4f7a-b059-75d32c27ca57', targetIndexName: 'restored-index', targetIndexId: '0d8aed24-adf8-4b77-8e10-fd674309dc85', status: 'Completed', createdAt: 2025-04-25T18:14:05.227Z, completedAt: 2025-04-25T18:14:11.074Z, percentComplete: 100 } ], pagination: undefined } ``` ```java Java theme={null} class RestoreJobList { data: [class RestoreJobModel { restoreJobId: cf597d76-4484-4b6c-b07c-2bfcac3388aa backupId: 0d75b99f-be61-4a93-905e-77201286c02e targetIndexName: restored-index targetIndexId: 8a810881-1505-46c0-b906-947c048b15f5 status: Completed createdAt: 2025-05-16T20:09:18.700631Z completedAt: 2025-05-16T20:11:30.673296Z percentComplete: 100.0 additionalProperties: null }, class RestoreJobModel { restoreJobId: 4902f735-b876-4e53-a05c-bc01d99251cb backupId: 8c85e612-ed1c-4f97-9f8c-8194e07bcf71 targetIndexName: restored-index2 targetIndexId: 710cb6e6-bfb4-4bf5-a425-9754e5bbc832 status: Completed createdAt: 2025-05-15T21:06:19.906074Z completedAt: 2025-05-15T21:06:39.360509Z percentComplete: 100.0 additionalProperties: null }] pagination: class PaginationResponse { next: eyJsaW1pdCI6Miwib2Zmc2V0IjoyfQ== additionalProperties: null } additionalProperties: null } ``` ```go Go theme={null} { "data": [ { "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "completed_at": "2025-05-16T20:11:30.673296Z", "created_at": "2025-05-16T20:09:18.700631Z", "percent_complete": 100, "restore_job_id": "e9ba8ff8-7948-4cfa-ba43-34227f6d30d4", "status": "Completed", "target_index_id": "025117b3-e683-423c-b2d1-6d30fbe5027f", "target_index_name": "restored-index" }, { "backup_id": "95707edb-e482-49cf-b5a5-312219a51a97", "completed_at": "2025-05-15T21:04:34.2463Z", "created_at": "2025-05-15T21:04:15.949067Z", "percent_complete": 100, "restore_job_id": "eee4f8b8-cd3e-45fe-9ed5-93c28e237f24", "status": "Completed", "target_index_id": "5a0d555f-7ccd-422a-a3a6-78f7b73350c0", "target_index_name": "restored-index2" } ], "pagination": { "next": "eyJsaW1pdCI6MTAsIm9mZnNldCI6MTB9" } } ``` ```json curl theme={null} { "data": [ { "restore_job_id": "9857add2-99d4-4399-870e-aa7f15d8d326", "backup_id": "94a63aeb-efae-4f7a-b059-75d32c27ca57", "target_index_name": "restored-index", "target_index_id": "0d8aed24-adf8-4b77-8e10-fd674309dc85", "status": "Completed", "created_at": "2025-04-25T18:14:05.227526Z", "completed_at": "2025-04-25T18:14:11.074618Z", "percent_complete": 100 }, { "restore_job_id": "69acc1d0-9105-4fcb-b1db-ebf97b285c5e", "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "target_index_name": "restored-index2", "target_index_id": "e6c0387f-33db-4227-9e91-32181106e56b", "status": "Completed", "created_at": "2025-05-14T17:25:59.378989Z", "completed_at": "2025-05-14T17:26:23.997284Z", "percent_complete": 100 } ], "pagination": null } ``` ## View restore job details You can [view the details of a specific restore job](/reference/api/latest/control-plane/describe_restore_job), as in the following example: ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") restore_job = pc.describe_restore_job(job_id="9857add2-99d4-4399-870e-aa7f15d8d326") print(restore_job) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) const restoreJob = await pc.describeRestoreJob('9857add2-99d4-4399-870e-aa7f15d8d326'); console.log(restoreJob); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.ApiException; import org.openapitools.db_control.client.model.*; public class CreateIndexFromBackup { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API-KEY").build(); RestoreJobModel restoreJob = pc.describeRestoreJob("9857add2-99d4-4399-870e-aa7f15d8d326"); System.out.println(restoreJob); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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) } restoreJob, err := pc.DescribeRestoreJob(ctx, "e9ba8ff8-7948-4cfa-ba43-34227f6d30d4") if err != nil { log.Fatalf("Failed to describe restore job: %v", err) } fmt.Printf(prettifyStruct(restoreJob)) } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" JOB_ID="9857add2-99d4-4399-870e-aa7f15d8d326" curl "https://api.pinecone.io/restore-jobs/$JOB_ID" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'accept: application/json' ``` The example returns a response like the following: ```python Python theme={null} {'backup_id': '94a63aeb-efae-4f7a-b059-75d32c27ca57', 'completed_at': datetime.datetime(2025, 4, 25, 18, 14, 11, 74618, tzinfo=tzutc()), 'created_at': datetime.datetime(2025, 4, 25, 18, 14, 5, 227526, tzinfo=tzutc()), 'percent_complete': 100.0, 'restore_job_id': '9857add2-99d4-4399-870e-aa7f15d8d326', 'status': 'Completed', 'target_index_id': '0d8aed24-adf8-4b77-8e10-fd674309dc85', 'target_index_name': 'restored-index'} ``` ```javascript JavaScript theme={null} { restoreJobId: '9857add2-99d4-4399-870e-aa7f15d8d326', backupId: '94a63aeb-efae-4f7a-b059-75d32c27ca57', targetIndexName: 'restored-index', targetIndexId: '0d8aed24-adf8-4b77-8e10-fd674309dc85', status: 'Completed', createdAt: 2025-04-25T18:14:05.227Z, completedAt: 2025-04-25T18:14:11.074Z, percentComplete: 100 } ``` ```java Java theme={null} class RestoreJobModel { restoreJobId: cf597d76-4484-4b6c-b07c-2bfcac3388aa backupId: 0d75b99f-be61-4a93-905e-77201286c02e targetIndexName: restored-index targetIndexId: 0d8aed24-adf8-4b77-8e10-fd674309dc85 status: Completed createdAt: 2025-05-16T20:09:18.700631Z completedAt: 2025-05-16T20:11:30.673296Z percentComplete: 100.0 additionalProperties: null } ``` ```go Go theme={null} { "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "completed_at": "2025-05-16T20:11:30.673296Z", "created_at": "2025-05-16T20:09:18.700631Z", "percent_complete": 100, "restore_job_id": "e9ba8ff8-7948-4cfa-ba43-34227f6d30d4", "status": "Completed", "target_index_id": "025117b3-e683-423c-b2d1-6d30fbe5027f", "target_index_name": "restored-index" } ``` ```json curl theme={null} { "restore_job_id": "9857add2-99d4-4399-870e-aa7f15d8d326", "backup_id": "94a63aeb-efae-4f7a-b059-75d32c27ca57", "target_index_name": "restored-index", "target_index_id": "0d8aed24-adf8-4b77-8e10-fd674309dc85", "status": "Completed", "created_at": "2025-04-25T18:14:05.227526Z", "completed_at": "2025-04-25T18:14:11.074618Z", "percent_complete": 100 } ``` # Target an index Source: https://docs.pinecone.io/guides/manage-data/target-an-index Target a Pinecone index by host URL (recommended for production) or by name for data operations like upsert, query, and fetch across SDKs. **Do not target an index by name in production.** When you target an index by name for data operations such as `upsert` and `query`, the SDK gets the unique DNS host for the index using the `describe_index` operation. This is convenient for testing but should be avoided in production because `describe_index` uses a different API than data operations and therefore adds an additional network call and point of failure. Instead, you should get an index host once and cache it for reuse or specify the host directly. ## Target by index host (recommended) This method is recommended for production: When using Private Endpoints for private connectivity between your application and Pinecone, you must target the index using the [Private Endpoint URL](/guides/production/configure-private-endpoints#read-and-write-data) for the host. ```Python Python {5} theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index(host="INDEX_HOST") ``` ```javascript JavaScript {6} theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); // For the Node.js SDK, you must specify both the index host and name. const index = pc.index("INDEX_NAME", "INDEX_HOST"); ``` ```java Java {11} theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; public class TargetIndexByHostExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); // For the Java SDK, you must specify both the index host and name. Index index = new Index(connection, "INDEX_NAME"); } } ``` ```go Go {21} theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } // This creates a new gRPC index connection, targeting the namespace "example-namespace" idxConnectionNs1, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host %v: %v", idx.Host, err) } // This reuses the gRPC index connection, targeting a different namespace idxConnectionNs2 := idxConnectionNs1.WithNamespace("example-namespace2") } ``` ### Get an index host You can get the unique DNS host for an index from the Pinecone console or the Pinecone API. To get an index host from the Pinecone console: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select the project containing the index. 3. Select the index. 4. Copy the URL under **HOST**. To get an index host from the Pinecone API, use the [`describe_index`](/reference/api/latest/control-plane/describe_index) operation, which returns the index host as the `host` value: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.describe_index(name="docs-example") # Response: # {'deletion_protection': 'disabled', # 'dimension': 1536, # 'host': 'docs-example-4zo0ijk.svc.us-east1-aws.pinecone.io', # 'metric': 'cosine', # 'name': 'docs-example', # 'spec': {'serverless': {'cloud': 'aws', 'region': 'us-east-1'}}, # 'status': {'ready': True, 'state': 'Ready'}} ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.describeIndex('docs-example'); // Response: // { // "name": "docs-example", // "dimension": 1536, // "metric": "cosine", // "host": "docs-example-4zo0ijk.svc.us-east1-aws.pinecone.io", // "deletionProtection": "disabled", // "spec": { // "serverless": { // "cloud": "aws", // "region": "us-east-1" // } // }, // "status": { // "ready": true, // "state": "Ready" // } // } ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class DescribeIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); IndexModel indexModel = pc.describeIndex("docs-example"); System.out.println(indexModel); } } // Response: // class IndexModel { // name: docs-example-java // dimension: 1536 // metric: cosine // host: docs-example-4zo0ijk.svc.us-west2-aws.pinecone.io // deletionProtection: enabled // spec: class IndexModelSpec { // pod: null // serverless: class ServerlessSpec { // cloud: aws // region: us-east-1 // } // } // status: class IndexModelStatus { // ready: true // state: Ready // } // } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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) } idx, err := pc.DescribeIndex(ctx, "docs-example") if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err) } else { fmt.Printf("index: %v\n", prettifyStruct(idx)) } } // Response: // index: { // "name": "docs-example", // "dimension": 1536, // "host": "docs-example-govk0nt.svc.apw5-4e34-81fa.pinecone.io", // "metric": "cosine", // "deletion_protection": "disabled", // "spec": { // "serverless": { // "cloud": "aws", // "region": "us-east-1" // } // }, // "status": { // "ready": true, // "state": "Ready" // } // } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/indexes/docs-example-curl" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" # Response: # { # "name": "docs-example", # "metric": "cosine", # "dimension": 1536, # "status": { # "ready": true, # "state": "Ready" # }, # "host": "docs-example-4zo0ijk.svc.us-east1-aws.pinecone.io", # "spec": { # "serverless": { # "region": "us-east-1", # "cloud": "aws" # } # } # } ``` ## Target by index name This method is convenient for testing but is not recommended for production: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index("docs-example") ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); // For the Node.js SDK, you must specify both the index host and name. const index = pc.index('docs-example'); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.clients.Pinecone; public class GenerateEmbeddings { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); Index index = pc.getIndexConnection("docs-example"); } } ``` ```go Go theme={null} // It is not possible to target an index by name in the Go SDK. // You must target an index by host. ``` # Update records Source: https://docs.pinecone.io/guides/manage-data/update-data Update Pinecone records by ID to change vector values or metadata, or update metadata across multiple records using a metadata filter expression. You can [update](/reference/api/latest/data-plane/update) a single record using the record ID or multiple records using a metadata filter. * **Update by ID**: Update a single record's metadata (add or change fields) or vector values. * **Update by metadata**: Update metadata (add or change fields) across multiple records using a metadata filter. Vector values cannot be updated. To update entire records, use the [upsert](/guides/index-data/upsert-data) operation instead. Updates consume [write units (WUs)](/guides/manage-cost/understanding-cost#write-units). See [Understanding cost](/guides/manage-cost/understanding-cost#update) for how update cost is calculated. ## Update by ID To update the vector and/or metadata of a single record, use the [`update`](/reference/api/latest/data-plane/update) operation with the following parameters: * `namespace`: The [namespace](/guides/index-data/indexing-overview#namespaces) containing the record to update. To use the default namespace, set the namespace to `"__default__"`. * `id`: The ID of the record to update. * One or both of the following: * Updated values for the vector. Specify one of the following: * `values`: For dense vectors. Must have the same length as the existing vector. * `sparse_values`: For sparse vectors. * `setMetadata`: The metadata to add or change. When updating metadata, only the specified metadata fields are modified, and if a specified metadata field does not exist, it is added. If a non-existent record ID is specified, no records are affected and a `200 OK` status is returned. In this example, assume you are updating the dense vector values and one metadata value of the following record in the `example-namespace` namespace: ``` ( namespace="example-namespace", id="id-3", values=[4.0, 2.0], setMetadata={"type": "doc", "genre": "drama"} ) ``` ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.update( namespace="example-namespace", id="id-3", values=[5.0, 3.0], set_metadata={"genre": "comedy"} ) ``` ```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/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") await index.namespace('example-namespace').update({ id: 'id-3', values: [5.0, 3.0], metadata: { genre: "comedy", }, }); ``` ```java Java theme={null} import com.google.protobuf.Struct; import com.google.protobuf.Value; import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.proto.UpdateResponse; import java.util.Arrays; import java.util.List; public class UpdateExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); List values = Arrays.asList(5.0f, 3.0f); Struct metaData = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("comedy").build()) .build(); UpdateResponse updateResponse = index.update("id-3", values, metaData, "example-namespace", null, null); System.out.println(updateResponse); } } ``` ```go Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" "google.golang.org/protobuf/types/known/structpb" ) 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/manage-data/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) } id := "id-3" metadataMap := map[string]interface{}{ "genre": "comedy", } metadataFilter, err := structpb.NewStruct(metadataMap) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } err = idxConnection.UpdateVector(ctx, &pinecone.UpdateVectorRequest{ Id: id, Values: []float32{5.0, 3.0}, Metadata: metadataFilter, }) if err != nil { log.Fatalf("Failed to update vector with ID %v: %v", id, err) } } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" # Update both values and metadata curl "https://$INDEX_HOST/vectors/update" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "id": "id-3", "values": [5.0, 3.0], "setMetadata": {"genre": "comedy"}, "namespace": "example-namespace" }' ``` After the update, the dense vector values and the `genre` metadata value are changed, but the `type` metadata value is unchanged: ``` ( id="id-3", values=[5.0, 3.0], metadata={"type": "doc", "genre": "comedy"} ) ``` ## Update by metadata To add or change metadata across multiple records in a namespace, use the `update` operation with the following parameters: * `namespace`: The [namespace](/guides/index-data/indexing-overview#namespaces) containing the records to update. To use the default namespace, set this to `"__default__"`. * `filter`: A [metadata filter expression](/guides/index-data/indexing-overview#metadata-filter-expressions) to match the records to update. * `setMetadata`: The metadata to add or change. When updating metadata, only the specified metadata fields are modified. If a specified metadata field does not exist, it is added. * `dry_run`: Optional. If `true`, the number of records that match the filter expression is returned, but the records are not updated. Each request updates a maximum of 100,000 records. Use `"dry_run": true` to check if you need to run the request multiple times. See the example below for details. For example, let's say you have records that represent chunks of a single document with metadata that keeps track of chunk and document details, and you want to store the author's name with each chunk of the document: ```json theme={null} { "id": "document1#chunk1", "values": [0.0236663818359375, -0.032989501953125, ..., -0.01041412353515625, 0.0086669921875], "metadata": { "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 1, "chunk_text": "First chunk of the document content...", "document_url": "https://example.com/docs/document1" } }, { "id": "document1#chunk2", "values": [-0.0412445068359375, 0.028839111328125, ..., 0.01953125, -0.0174560546875], "metadata": { "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 2, "chunk_text": "Second chunk of the document content...", "document_url": "https://example.com/docs/document1" } }, ... ``` The following code updates all matching records with the new `author` metadata field: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") # Use dry_run to check how many records match the filter dry_run_response = index.update( namespace="example-namespace", filter={"document_title": {"$eq": "Introduction to Vector Databases"}}, set_metadata={"author": "Del Klein"}, dry_run=True ) print(dry_run_response.matched_records) # Perform the update response = index.update( namespace="example-namespace", filter={"document_title": {"$eq": "Introduction to Vector Databases"}}, set_metadata={"author": "Del Klein"} ) ``` ```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/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") await index.namespace('example-namespace').update({ filter: { document_title: { $eq: 'Introduction to Vector Databases' } }, metadata: { author: 'Del Klein' }, }); ``` ```java Java theme={null} import com.google.protobuf.Struct; import com.google.protobuf.Value; import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.proto.UpdateResponse; public class UpdateByMetadataExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); Struct filter = Struct.newBuilder() .putFields("document_title", Value.newBuilder() .setStructValue(Struct.newBuilder() .putFields("$eq", Value.newBuilder() .setStringValue("Introduction to Vector Databases") .build()) .build()) .build()) .build(); Struct metadata = Struct.newBuilder() .putFields("author", Value.newBuilder() .setStringValue("Del Klein") .build()) .build(); // Dry run to check how many records match UpdateResponse dryRunResponse = index.updateByMetadata( filter, metadata, "example-namespace", true); System.out.println("Matched records: " + dryRunResponse.getMatchedRecords()); // Perform the update UpdateResponse response = index.updateByMetadata( filter, metadata, "example-namespace"); System.out.println(response); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" "google.golang.org/protobuf/types/known/structpb" ) 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/manage-data/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) } filter, err := structpb.NewStruct(map[string]interface{}{ "document_title": map[string]interface{}{ "$eq": "Introduction to Vector Databases", }, }) if err != nil { log.Fatalf("Failed to create filter: %v", err) } metadata, err := structpb.NewStruct(map[string]interface{}{ "author": "Del Klein", }) if err != nil { log.Fatalf("Failed to create metadata: %v", err) } // Dry run to check how many records match dryRun := true dryRunRes, err := idxConnection.UpdateVectorsByMetadata(ctx, &pinecone.UpdateVectorsByMetadataRequest{ Filter: filter, Metadata: metadata, DryRun: &dryRun, }) if err != nil { log.Fatalf("Failed to dry run update: %v", err) } fmt.Printf("Matched records: %d\n", dryRunRes.MatchedRecords) // Perform the update res, err := idxConnection.UpdateVectorsByMetadata(ctx, &pinecone.UpdateVectorsByMetadataRequest{ Filter: filter, Metadata: metadata, }) if err != nil { log.Fatalf("Failed to update vectors by metadata: %v", err) } fmt.Printf("Updated records: %d\n", res.MatchedRecords) } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/vectors/update" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "namespace": "example-namespace", "filter": { "document_title": {"$eq": "Introduction to Vector Databases"} }, "setMetadata": { "author": "Del Klein" } }' ``` ### Handling large updates If you need to update most of the records in a large namespace, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) for help creating an export to enable a faster and more cost-effective approach. Each request updates a maximum of 100,000 records. For larger datasets, use `dry_run` to check the count and repeat the request as needed: 1. To check how many records match the filter expression, send a request with `dry_run` set to `true`: ```bash curl {11} theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/vectors/update" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "dry_run": true, "namespace": "example-namespace", "filter": { "document_title": {"$eq": "Introduction to Vector Databases"} }, "setMetadata": { "author": "Del Klein" } }' ``` The response contains the number of records that match the filter expression: ```json theme={null} { "matchedVectors": 150000 } ``` Since this number exceeds the 100,000 record limit, you'll need to run the update request multiple times. 2. Initiate the first update by sending the request without the `dry_run` parameter: ```bash curl theme={null} curl "https://$INDEX_HOST/vectors/update" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "namespace": "example-namespace", "filter": { "document_title": {"$eq": "Introduction to Vector Databases"} }, "setMetadata": { "author": "Del Klein" } }' ``` Again, the response contains the total number of records that match the filter expression, but only 100,000 will be updated: ```json theme={null} { "matchedVectors": 150000 } ``` 3. Pinecone is eventually consistent, so there can be a slight delay before your update request is processed. Repeat the `dry_run` request until the number of matching records shows that the first 100,000 records have been updated: ```bash curl {11} theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/vectors/update" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "dry_run": true, "namespace": "example-namespace", "filter": { "document_title": {"$eq": "Introduction to Vector Databases"} }, "setMetadata": { "author": "Del Klein" } }' ``` ```json theme={null} { "matchedVectors": 50000 } ``` 4. Once the first 100,000 records have been updated, update the remaining records: ```bash curl theme={null} curl "https://$INDEX_HOST/vectors/update" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "namespace": "example-namespace", "filter": { "document_title": {"$eq": "Introduction to Vector Databases"} }, "setMetadata": { "author": "Del Klein" } }' ``` 5. Repeat the `dry_run` request until the number of matching records shows that the remaining records have been updated: ```bash curl {11} theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/vectors/update" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "dry_run": true, "namespace": "example-namespace", "filter": { "document_title": {"$eq": "Introduction to Vector Databases"} }, "setMetadata": { "author": "Del Klein" } }' ``` ```json theme={null} { "matchedVectors": 0 } ``` Once the request has completed, all matching records include the author name as metadata: ```json {10,22} theme={null} { "id": "document1#chunk1", "values": [0.0236663818359375, -0.032989501953125, ..., -0.01041412353515625, 0.0086669921875], "metadata": { "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 1, "chunk_text": "First chunk of the document content...", "document_url": "https://example.com/docs/document1", "author": "Del Klein" } }, { "id": "document1#chunk2", "values": [-0.0412445068359375, 0.028839111328125, ..., 0.01953125, -0.0174560546875], "metadata": { "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 2, "chunk_text": "Second chunk of the document content...", "document_url": "https://example.com/docs/document1", "author": "Del Klein" } }, ... ``` ### Limitations * Each request updates a maximum of 100,000 records. Use `"dry_run": true` to check if you need to run the request multiple times. See the example above for details. * You can add or change metadata across multiple records, but you cannot remove metadata fields. ## Remove a metadata field To remove a metadata field from a record, use the [upsert](/guides/index-data/upsert-data) operation to replace the record's metadata, providing the record's existing ID and vector values along with only the metadata you want to keep. Because upsert replaces a record's metadata in full, any fields you omit are cleared. ## Data freshness Pinecone is eventually consistent, so there can be a slight delay before updates are visible to queries. You can [use log sequence numbers](/guides/index-data/check-data-freshness#check-the-log-sequence-number) to check whether an update request has completed. ## See also * [Update an entire document](/guides/index-data/data-modeling#update-an-entire-document) # Integrate with Amazon S3 Source: https://docs.pinecone.io/guides/operations/integrations/integrate-with-amazon-s3 Connect Pinecone to an Amazon S3 bucket using an IAM role to import data and export audit logs. This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). This page shows you how to integrate Pinecone with an Amazon S3 bucket. Once your integration is set up, you can use it to [import data](/guides/index-data/import-data) from your Amazon S3 bucket into a Pinecone index hosted on AWS, or to [export audit logs](/guides/production/configure-audit-logs) to your Amazon S3 bucket. ## Before you begin Ensure you have the following: * A [Pinecone account](https://app.pinecone.io/). * An [Amazon S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-buckets.html). ## 1. Create an IAM policy In the [AWS IAM console](https://console.aws.amazon.com/iam/home): 1. In the navigation pane, click **Policies**. 2. Click **Create policy**. 3. In **Select a service** section, select **S3**. 4. Select the following actions to allow: * `ListBucket`: Permission to list some or all of the objects in an S3 bucket. Required for [importing data](/guides/index-data/import-data) and [exporting audit logs](/guides/production/configure-audit-logs). * `GetObject`: Permission to retrieve objects from an S3 bucket. Required for [importing data](/guides/index-data/import-data). * `PutObject`: Permission to add an object to an S3 bucket. Required for [exporting audit logs](/guides/production/configure-audit-logs). 5. In the **Resources** section, select **Specific**. 6. For the **bucket**, specify the ARN of the bucket you created. For example: `arn:aws:s3:::example-bucket-name` 7. For the **object**, specify an object ARN as the target resource. For example: `arn:aws:s3:::example-bucket-name/*` 8. Click **Next**. 9. Specify the name of your policy. For example: "Pinecone-S3-Access". 10. Click **Create policy**. ### Targeting a subdirectory (optional) To write [audit logs](/guides/production/configure-audit-logs) to a specific subdirectory within your S3 bucket (e.g., `my-bucket/pinecone-logs/`), you need to configure your IAM policy differently for `ListBucket` vs. object-level actions: 1. For `ListBucket`, use a **Condition** block with `StringLike` to specify the prefix. Include both the directory path with and without the trailing wildcard: ```json theme={null} { "Sid": "ListBucketWithPrefix", "Effect": "Allow", "Action": "s3:ListBucket", "Resource": "arn:aws:s3:::example-bucket-name", "Condition": { "StringLike": { "s3:prefix": [ "pinecone-logs/", "pinecone-logs/*" ] } } } ``` 2. For `PutObject` and `GetObject`, use the **Resource** specifier with the subdirectory path: ```json theme={null} { "Sid": "ObjectActionsInSubdirectory", "Effect": "Allow", "Action": [ "s3:PutObject", "s3:GetObject" ], "Resource": "arn:aws:s3:::example-bucket-name/pinecone-logs/*" } ``` **Complete example policy for subdirectory access:** ```json theme={null} { "Version": "2012-10-17", "Statement": [ { "Sid": "ListBucketWithPrefix", "Effect": "Allow", "Action": "s3:ListBucket", "Resource": "arn:aws:s3:::example-bucket-name", "Condition": { "StringLike": { "s3:prefix": [ "pinecone-logs/", "pinecone-logs/*" ] } } }, { "Sid": "ObjectActionsInSubdirectory", "Effect": "Allow", "Action": [ "s3:PutObject", "s3:GetObject" ], "Resource": "arn:aws:s3:::example-bucket-name/pinecone-logs/*" } ] } ``` The key difference is that `ListBucket` operates on the bucket resource and uses conditions to filter by prefix, while object-level actions (`PutObject`, `GetObject`) operate directly on object resources specified in the ARN. ## 2. Set up access using an IAM role In the [AWS IAM console](https://console.aws.amazon.com/iam/home): 1. In the navigation pane, click **Roles**. 2. Click **Create role**. 3. In the **Trusted entity type** section, select **AWS account**. 4. Select **Another AWS account**. 5. Enter the Pinecone AWS VPC account ID: `713131977538` 6. Click **Next**. 7. Select the [policy you created](#1-create-an-iam-policy). 8. Click **Next**. 9. Specify the role name. For example: "Pinecone". 10. Click **Create role**. 11. Click the role you created. 12. On the **Summary** page for the role, find the **ARN**. For example: `arn:aws:iam::123456789012:role/PineconeAccess` 13. Copy the **ARN**. You will need to enter the ARN into Pinecone later. ## 3. Add a storage integration This step is required for [importing data](/guides/index-data/import-data). It is not required for [storing audit logs](/guides/production/configure-audit-logs). In the [Pinecone console](https://app.pinecone.io/organizations/-/projects), add an integration with Amazon S3.. 1. Select your project. 2. Go to [**Manage > Storage integrations**](https://app.pinecone.io/organizations/-/projects/-/storage). 3. Click **Add integration**. 4. Enter a unique integration name. 5. Select **Amazon S3**. 6. Enter the **ARN** of the [IAM role you created](/guides/operations/integrations/integrate-with-amazon-s3#2-set-up-access-using-an-iam-role). 7. Click **Add integration**. ## Next steps * [Import data](/guides/index-data/import-data) from your Amazon S3 bucket into a Pinecone index. * [Configure audit logs](/guides/production/configure-audit-logs) to export logs to your Amazon S3 bucket. # Integrate with Azure Blob Storage Source: https://docs.pinecone.io/guides/operations/integrations/integrate-with-azure-blob-storage Connect Pinecone to Azure Blob Storage using a service principal to import data into your indexes. This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). This page describes how to integrate Pinecone with Azure Blob Storage. After setting up an integration, you can [import data](/guides/index-data/import-data) from an Azure Blob Storage container into a Pinecone index hosted on AWS, GCP, or Azure. ## Before you begin Ensure you have the following: * A [Pinecone account](https://app.pinecone.io/) * An [Azure Blob Storage container](https://learn.microsoft.com/azure/storage/blobs/storage-blobs-introduction) ## 1. Create an app registration and service principal Pinecone uses a service principal to access your Azure Blob Storage container. 1. [Create an app registration](https://learn.microsoft.com/entra/identity-platform/quickstart-register-app) for your Pinecone integration. This automatically creates a service principal. When creating your app registration: * Do not specify a **Redirect URI**. * Copy the **Application (client) ID** and the **Directory (tenant) ID**. You'll use these values when adding a storage integration in Pinecone. 2. [Create a client secret](https://learn.microsoft.com/entra/identity-platform/how-to-add-credentials?tabs=client-secret) for the service principal. Copy the secret's **Value** (not its **ID**). You'll use this when creating a storage integration in Pinecone. ## 2. Grant access to the storage account [Assign the service principal to your storage account](https://learn.microsoft.com/azure/storage/common/storage-auth-aad-rbac-portal#assign-azure-rbac-roles-using-the-azure-portal): 1. In the Azure portal, navigate to the subscription associated with your storage account. 2. Select **Access control (IAM)**. 3. Click **Add** > **Add role assignment**. 4. Select **Storage Blob Data Reader** or another role that has permission to list and read blobs in a container. 5. Click **Next**. 6. Select **User, group, or service principal** and click **Select members**. 7. Select the app you created in the previous step. 8. Click **Review + assign** (you may need to click this twice). ## 3. In Pinecone, add a storage integration In the [Pinecone console](https://app.pinecone.io/organizations/-/projects), add an integration with Azure Blob Storage: 1. Select your project. 2. Go to [**Manage > Storage integrations**](https://app.pinecone.io/organizations/-/projects/-/storage). 3. Click **Add integration**. 4. Enter a unique integration name. 5. Select **Azure Blob Storage**. 6. For **Tenant ID**, **Client ID**, and **Client secret**, enter the values you copied from Azure. 7. Click **Add integration**. ## Next steps [Import data](/guides/index-data/import-data) from your Azure Blob Storage container into your Pinecone index. # Integrate with Google Cloud Storage Source: https://docs.pinecone.io/guides/operations/integrations/integrate-with-google-cloud-storage Connect Pinecone to a Google Cloud Storage bucket with a service account key to import data into your indexes. This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). This page shows you how to integrate Pinecone with a Google Cloud Storage (GCS) bucket. Once your integration is set up, you can use it to [import data](/guides/index-data/import-data) from your bucket into a Pinecone index hosted on AWS, GCP, or Azure. ## Before you begin Ensure you have the following: * A [Pinecone account](https://app.pinecone.io/) * A [Google Cloud Storage bucket](https://cloud.google.com/storage/docs/creating-buckets) ## 1. Create a service account and key Pinecone will use a service account to access your GCS bucket. 1. [Create a service account](https://cloud.google.com/iam/docs/service-accounts-create) for your Pinecone integration. 2. [Create a service account key](https://cloud.google.com/iam/docs/keys-create-delete#creating). Select **JSON** as the key type. The key will be downloaded to your computer. You'll use this key when adding a storage integration in Pinecone. ## 2. Grant access to the bucket [Add your service account as a principal to the bucket](https://cloud.google.com/storage/docs/access-control/using-iam-permissions#bucket-add). * For the principal, use your service account email address. * For the role, select **Storage Object Viewer** or another role that has permission to list and read objects in a bucket. ## 3. Add a storage integration In the [Pinecone console](https://app.pinecone.io/organizations/-/projects), add an integration with Google Cloud Storage: 1. Select your project. 2. Go to [**Manage > Storage integrations**](https://app.pinecone.io/organizations/-/projects/-/storage). 3. Click **Add integration**. 4. Enter a unique integration name. 5. Select **Google Cloud Storage**. 6. Open the JSON key file for your service account. 7. Copy the contents of the key file and paste them into the **Index account key JSON** field. 8. Click **Add integration**. ## Next steps [Import data](/guides/index-data/import-data) from your GCS bucket into your Pinecone index. # Manage storage integrations Source: https://docs.pinecone.io/guides/operations/integrations/manage-storage-integrations Update or delete existing Amazon S3, Google Cloud Storage, and Azure Blob storage integrations for your Pinecone project in the console. This feature is available on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). This page shows you how to manage storage integrations for your Pinecone project. To set up cloud storage for integration with Pinecone, see the following guides: * [Integrate with Amazon S3](/guides/operations/integrations/integrate-with-amazon-s3) * [Integrate with Google Cloud Storage](/guides/operations/integrations/integrate-with-google-cloud-storage) * [Integrate with Azure Blob Storage](/guides/operations/integrations/integrate-with-azure-blob-storage) ## Update an integration To update information for a storage integration through the [Pinecone console](https://app.pinecone.io/organizations/-/projects), take the following steps: 1. Select your project. 2. Go to [**Manage > Storage integrations**](https://app.pinecone.io/organizations/-/projects/-/storage). 3. For the integration you want to update, click the *...* (Actions) icon. 4. Click **Manage**. 5. Update the integration details as needed. 6. Click **Add integration**. ## Delete an integration To delete a storage integration through the [Pinecone console](https://app.pinecone.io/organizations/-/projects), take the following steps: 1. Select your project. 2. Go to [**Manage > Storage integrations**](https://app.pinecone.io/organizations/-/projects/-/storage). 3. For the integration you want to update, click the *...* (Actions) icon. 4. Click **Delete**. 5. Enter the integration name. 6. Click **Confirm deletion**. # Local development with Pinecone Local Source: https://docs.pinecone.io/guides/operations/local-development Run Pinecone Local, an in-memory Docker emulator, to develop and test apps offline without an account or usage fees. Pinecone Local is an in-memory Pinecone emulator available as a Docker image. This page shows you how to use Pinecone Local to develop your applications locally without connecting to your Pinecone account or incurring usage or storage fees. Pinecone Local is not suitable for production. See [Limitations](#limitations) for details. ## Limitations Pinecone Local has the following limitations: * Pinecone Local uses the `2025-01` API version, which is not the latest stable version. * Pinecone Local is available in Docker only. * Pinecone Local is an in-memory emulator and is not suitable for production. Records loaded into Pinecone Local do not persist after it is stopped. * Pinecone Local does not authenticate client requests. API keys are ignored. * Max number of records per index: 100,000. Pinecone Local does not currently support the following features: * [Import from object storage](/guides/index-data/import-data) * [Backup/restore of serverless indexes](/guides/manage-data/backups-overview) * [Collections for pod-based indexes](/guides/indexes/pods/understanding-collections) * [Namespace management](/guides/manage-data/manage-namespaces) * [Pinecone Inference](/reference/api/introduction#inference) * [Pinecone Assistant](/guides/assistant/overview) ## 1. Start Pinecone Local You can configure Pinecone Local as an index emulator or database emulator: * **Index emulator** - This approach uses the `pinecone-index` Docker image to create and configure indexes on startup. This is recommended when you want to quickly experiment with reading and writing data without needing to manage the index lifecycle. With index emulation, you can only read and write data to the indexes created at startup. You cannot create new indexes, list indexes, or run other operations that do not involve reading and writing data. * **Database emulator** - This approach uses the `pinecone-local` Docker image to emulate Pinecone Database more broadly. This is recommended when you want to test your production app or manually create and manage indexes. ### Index emulator Make sure [Docker](https://docs.docker.com/get-docker/) is installed and running on your local machine. Create a `docker-compose.yaml` file that defines a service for each index that Pinecone Local should create on startup. In this file, include the `pinecone-index` Docker image, a localhost port for the index to use, and other details: ```yaml theme={null} services: dense-index: image: ghcr.io/pinecone-io/pinecone-index:latest container_name: dense-index environment: PORT: 5081 INDEX_TYPE: serverless VECTOR_TYPE: dense DIMENSION: 2 METRIC: cosine ports: - "5081:5081" platform: linux/amd64 sparse-index: image: ghcr.io/pinecone-io/pinecone-index:latest container_name: sparse-index environment: PORT: 5082 INDEX_TYPE: serverless VECTOR_TYPE: sparse DIMENSION: 0 METRIC: dotproduct ports: - "5082:5082" platform: linux/amd64 ``` For each index, update the environment variables as needed: * `PORT`: Specify the port number for the index to listen on. * `INDEX_TYPE`: Specify the type of Pinecone index to create. Accepted values: `serverless` or `pod`. * `VECTOR_TYPE`: Specify the [type of vectors](/guides/index-data/indexing-overview#indexes) you will store in the index. Accepted values: `dense` or `sparse`. Sparse is supported only with serverless indexes. * `DIMENSION`: Specify the dimension of vectors you will store in the index. For indexes that store only sparse vectors, this must be set to `0`. * `METRIC`: Specify the [distance metric](/guides/index-data/indexing-overview#distance-metrics) for calculating the similarity between vectors in the index. Accepted values when storing dense vectors: `cosine`, `euclidean`, or `dotproduct`. Accepted value when storing only sparse vectors: `dotproduct`. To start Pinecone Local, run the following command: ```shell theme={null} docker compose up -d ``` You'll see a message with details about each index. Make sure [Docker](https://docs.docker.com/get-docker/) is installed and running on your local machine. Download the latest `pinecone-index` Docker image: ```shell theme={null} docker pull ghcr.io/pinecone-io/pinecone-index:latest ``` Start Pinecone Local with one or more indexes: ```shell theme={null} docker run -d \ --name dense-index \ -e PORT=5081 \ -e INDEX_TYPE=serverless \ -e VECTOR_TYPE=dense \ -e DIMENSION=2 \ -e METRIC=cosine \ -p 5081:5081 \ --platform linux/amd64 \ ghcr.io/pinecone-io/pinecone-index:latest ``` ```shell theme={null} docker run -d \ --name sparse-index \ -e PORT=5082 \ -e INDEX_TYPE=serverless \ -e VECTOR_TYPE=sparse \ -e DIMENSION=0 \ -e METRIC=dotproduct \ -p 5082:5082 \ --platform linux/amd64 \ ghcr.io/pinecone-io/pinecone-index:latest ``` For each index, update the environment variables as needed: * `PORT`: Specify the port number for the index to listen on. * `INDEX_TYPE`: Specify the type of Pinecone index to create. Accepted values: `serverless` or `pod`. * `VECTOR_TYPE`: Specify the [type of vectors](/guides/index-data/indexing-overview#indexes) you will store in the index. Accepted values: `dense` or `sparse`. Sparse is supported only with serverless indexes. * `DIMENSION`: Specify the dimension of vectors you will store in the index. For indexes that store only sparse vectors, this must be set to `0`. * `METRIC`: Specify the [distance metric](/guides/index-data/indexing-overview#distance-metrics) for calculating the similarity between vectors in the index. Accepted values when storing dense vectors: `cosine`, `euclidean`, or `dotproduct`. Accepted value when storing only sparse vectors: `dotproduct`. ### Database emulator Make sure [Docker](https://docs.docker.com/get-docker/) is installed and running on your local machine. Create a `docker-compose.yaml` file that defines a service for Pinecone local, including the `pinecone-local` Docker image, the host and port that Pinecone Local will run on and the range of ports that will be available for indexes: ```yaml theme={null} services: pinecone: image: ghcr.io/pinecone-io/pinecone-local:latest environment: PORT: 5080 PINECONE_HOST: localhost ports: - "5080-5090:5080-5090" platform: linux/amd64 ``` To start Pinecone Local, run the following command: ```shell theme={null} docker compose up -d ``` You'll see a message with details about the Pinecone Local instance. Make sure [Docker](https://docs.docker.com/get-docker/) is installed and running on your local machine. Download the latest `pinecone-local` Docker image: ```shell theme={null} docker pull ghcr.io/pinecone-io/pinecone-local:latest ``` Start Pinecone Local: ```shell theme={null} docker run -d \ --name pinecone-local \ -e PORT=5080 \ -e PINECONE_HOST=localhost \ -p 5080-5090:5080-5090 \ --platform linux/amd64 \ ghcr.io/pinecone-io/pinecone-local:latest ``` This command defines the host and port that Pinecone Local will run on, as well as the range of ports that will be available for indexes. ## 2. Develop your app Running code against Pinecone Local is just like running code against your Pinecone account, with the following differences: * Pinecone Local does not authenticate client requests. API keys are ignored. * The latest version of Pinecone Local uses [Pinecone API version](/reference/api/versioning) `2025-01` and requires [Python SDK](/reference/sdks/python/overview) `v6.x` or later, [Node.js SDK](/reference/sdks/node/overview) `v5.x` or later, [Java SDK](/reference/sdks/java/overview) `v4.x` or later, and [Go SDK](/reference/sdks/go/overview) `v3.x` or later. Be sure to review the [limitations](#limitations) of Pinecone Local before using it for development or testing. **Example** The following example assumes that you have [started Pinecone Local without indexes](/guides/operations/local-development#database-emulator). It initializes a client, creates [an index for dense vectors](/guides/index-data/indexing-overview#indexes-with-dense-vectors) and [an index for sparse vectors](/guides/index-data/indexing-overview#indexes-with-sparse-vectors), upserts records into each, checks their record counts, and queries them. ```python Python theme={null} from pinecone.grpc import PineconeGRPC, GRPCClientConfig from pinecone import ServerlessSpec # Initialize a client. # API key is required, but the value does not matter. # Host and port of the Pinecone Local instance # is required when starting without indexes. pc = PineconeGRPC( api_key="pclocal", host="http://localhost:5080" ) # Create two indexes, one dense and one sparse dense_index_name = "dense-index" sparse_index_name = "sparse-index" if not pc.has_index(dense_index_name): dense_index_model = pc.create_index( name=dense_index_name, vector_type="dense", dimension=2, metric="cosine", spec=ServerlessSpec(cloud="aws", region="us-east-1"), deletion_protection="disabled", tags={"environment": "development"} ) print("Index model (dense):\n", dense_index_model) if not pc.has_index(sparse_index_name): sparse_index_model = pc.create_index( name=sparse_index_name, vector_type="sparse", metric="dotproduct", spec=ServerlessSpec(cloud="aws", region="us-east-1"), deletion_protection="disabled", tags={"environment": "development"} ) print("\nIndex model (sparse):\n", sparse_index_model) # Target each index, disabling tls dense_index_host = pc.describe_index(name=dense_index_name).host dense_index = pc.Index(host=dense_index_host, grpc_config=GRPCClientConfig(secure=False)) sparse_index_host = pc.describe_index(name=sparse_index_name).host sparse_index = pc.Index(host=sparse_index_host, grpc_config=GRPCClientConfig(secure=False)) # Upsert records into the index (dense) dense_index.upsert( vectors=[ { "id": "vec1", "values": [1.0, -2.5], "metadata": {"genre": "drama"} }, { "id": "vec2", "values": [3.0, -2.0], "metadata": {"genre": "documentary"} }, { "id": "vec3", "values": [0.5, -1.5], "metadata": {"genre": "documentary"} } ], namespace="example-namespace" ) # Upsert records into the index (sparse) sparse_index.upsert( namespace="example-namespace", vectors=[ { "id": "vec1", "sparse_values": { "values": [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688], "indices": [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191] }, "metadata": { "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "category": "technology", "quarter": "Q3" } }, { "id": "vec2", "sparse_values": { "values": [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469], "indices": [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697] }, "metadata": { "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4" } }, { "id": "vec3", "sparse_values": { "values": [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094], "indices": [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697] }, "metadata": { "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", "category": "technology", "quarter": "Q3" } } ] ) # Check the number of records in each index print("\nIndex stats (dense):\n", dense_index.describe_index_stats()) print("\nIndex stats (sparse):\n", sparse_index.describe_index_stats()) # Query the index (dense) with a metadata filter dense_response = dense_index.query( namespace="example-namespace", vector=[3.0, -2.0], filter={"genre": {"$eq": "documentary"}}, top_k=1, include_values=False, include_metadata=True ) print("\nDense query response:\n", dense_response) # Query the index (sparse) with a metadata filter sparse_response = sparse_index.query( namespace="example-namespace", sparse_vector={ "values": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0], "indices": [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697] }, filter={ "quarter": {"$eq": "Q4"} }, top_k=1, include_values=False, include_metadata=True ) print("/nSparse query response:\n", sparse_response) # Delete the indexes pc.delete_index(name=dense_index_name) pc.delete_index(name=sparse_index_name) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; // Initialize a client. // API key is required, but the value does not matter. // Host and port of the Pinecone Local instance // is required when starting without indexes. const pc = new Pinecone({ apiKey: 'pclocal', controllerHostUrl: 'http://localhost:5080' }); // Create two indexes, one dense and one sparse const denseIndexName = 'dense-index'; const sparseIndexName = 'sparse-index'; const denseIndexModel = await pc.createIndex({ name: denseIndexName, vectorType: 'dense', dimension: 2, metric: 'cosine', spec: { serverless: { cloud: 'aws', region: 'us-east-1' } }, deletionProtection: 'disabled', tags: { environment: 'development' }, }); console.log('Index model (dense):', denseIndexModel); const sparseIndexModel = await pc.createIndex({ name: sparseIndexName, vectorType: 'sparse', metric: 'dotproduct', spec: { serverless: { cloud: 'aws', region: 'us-east-1' } }, deletionProtection: 'disabled', tags: { environment: 'development' }, }); console.log('\nIndex model (sparse):', sparseIndexModel); // Target each index const denseIndexHost = (await pc.describeIndex(denseIndexName)).host; const denseIndex = await pc.index(denseIndexName, 'http://' + denseIndexHost); const sparseIndexHost = (await pc.describeIndex(sparseIndexName)).host; const sparseIndex = await pc.index(sparseIndexName, 'http://' + sparseIndexHost); // Upsert records into the index (dense) await denseIndex.namespace('example-namespace').upsert([ { id: 'vec1', values: [1.0, -2.5], metadata: { genre: 'drama' }, }, { id: 'vec2', values: [3.0, -2.0], metadata: { genre: 'documentary' }, }, { id: 'vec3', values: [0.5, -1.5], metadata: { genre: 'documentary' }, } ]); // Upsert records into the index (sparse) await sparseIndex.namespace('example-namespace').upsert([ { id: 'vec1', sparseValues: { indices: [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191], values: [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688] }, metadata: { chunk_text: 'AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.', category: 'technology', quarter: 'Q3' } }, { id: 'vec2', sparseValues: { indices: [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697], values: [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469] }, metadata: { chunk_text: "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.", category: 'technology', quarter: 'Q4' } }, { id: 'vec3', sparseValues: { indices: [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697], values: [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094] }, metadata: { chunk_text: "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", category: 'technology', quarter: 'Q3' } } ]); // Check the number of records in each index console.log('\nIndex stats (dense):', await denseIndex.describeIndexStats()); console.log('\nIndex stats (sparse):', await sparseIndex.describeIndexStats()); // Query the index (dense) with a metadata filter const denseQueryResponse = await denseIndex.namespace('example-namespace').query({ vector: [3.0, -2.0], filter: { 'genre': {'$eq': 'documentary'} }, topK: 1, includeValues: false, includeMetadata: true, }); console.log('\nDense query response:', denseQueryResponse); const sparseQueryResponse = await sparseIndex.namespace('example-namespace').query({ sparseVector: { indices: [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697], values: [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0] }, topK: 1, includeValues: false, includeMetadata: true }); console.log('\nSparse query response:', sparseQueryResponse); // Delete the index await pc.deleteIndex(denseIndexName); await pc.deleteIndex(sparseIndexName); ``` ```java Java theme={null} import com.google.protobuf.Struct; import com.google.protobuf.Value; import io.pinecone.clients.Index; import io.pinecone.clients.Pinecone; import io.pinecone.proto.DescribeIndexStatsResponse; import org.openapitools.db_control.client.model.DeletionProtection; import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices; import java.util.*; public class PineconeLocalExample { public static void main(String[] args) { // Initialize a client. // API key is required, but the value does not matter. // When starting without indexes, disable TLS and // provide the host and port of the Pinecone Local instance. String host = "http://localhost:5080"; Pinecone pc = new Pinecone.Builder("pclocal") .withHost(host) .withTlsEnabled(false) .build(); // Create two indexes, one dense and one sparse String denseIndexName = "dense-index"; String sparseIndexName = "sparse-index"; HashMap tags = new HashMap<>(); tags.put("environment", "development"); pc.createServerlessIndex( denseIndexName, "cosine", 2, "aws", "us-east-1", DeletionProtection.DISABLED, tags ); pc.createSparseServelessIndex( sparseIndexName, "aws", "us-east-1", DeletionProtection.DISABLED, tags, "sparse" ); // Get index connection objects Index denseIndexConnection = pc.getIndexConnection(denseIndexName); Index sparseIndexConnection = pc.getIndexConnection(sparseIndexName); // Upsert records into the index (dense) Struct metaData1 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("drama").build()) .build(); Struct metaData2 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("documentary").build()) .build(); Struct metaData3 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("documentary").build()) .build(); denseIndexConnection.upsert("vec1", Arrays.asList(1.0f, -2.5f), null, null, metaData1, "example-namespace"); denseIndexConnection.upsert("vec2", Arrays.asList(3.0f, -2.0f), null, null, metaData2, "example-namespace"); denseIndexConnection.upsert("vec3", Arrays.asList(0.5f, -1.5f), null, null, metaData3, "example-namespace"); // Upsert records into the index (sparse) ArrayList indices1 = new ArrayList<>(Arrays.asList( 822745112L, 1009084850L, 1221765879L, 1408993854L, 1504846510L, 1596856843L, 1640781426L, 1656251611L, 1807131503L, 2543655733L, 2902766088L, 2909307736L, 3246437992L, 3517203014L, 3590924191L )); ArrayList values1 = new ArrayList<>(Arrays.asList( 1.7958984f, 0.41577148f, 2.828125f, 2.8027344f, 2.8691406f, 1.6533203f, 5.3671875f, 1.3046875f, 0.49780273f, 0.5722656f, 2.71875f, 3.0820312f, 2.5019531f, 4.4414062f, 3.3554688f )); Struct sparseMetaData1 = Struct.newBuilder() .putFields("chunk_text", Value.newBuilder().setStringValue("AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.").build()) .putFields("category", Value.newBuilder().setStringValue("technology").build()) .putFields("quarter", Value.newBuilder().setStringValue("Q3").build()) .build(); ArrayList indices2 = new ArrayList<>(Arrays.asList( 131900689L, 592326839L, 710158994L, 838729363L, 1304885087L, 1640781426L, 1690623792L, 1807131503L, 2066971792L, 2428553208L, 2548600401L, 2577534050L, 3162218338L, 3319279674L, 3343062801L, 3476647774L, 3485013322L, 3517203014L, 4283091697L )); ArrayList values2 = new ArrayList<>(Arrays.asList( 0.4362793f, 3.3457031f, 2.7714844f, 3.0273438f, 3.3164062f, 5.6015625f, 2.4863281f, 0.38134766f, 1.25f, 2.9609375f, 0.34179688f, 1.4306641f, 0.34375f, 3.3613281f, 1.4404297f, 2.2558594f, 2.2597656f, 4.8710938f, 0.5605469f )); Struct sparseMetaData2 = Struct.newBuilder() .putFields("chunk_text", Value.newBuilder().setStringValue("Analysts suggest that AAPL'\\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.").build()) .putFields("category", Value.newBuilder().setStringValue("technology").build()) .putFields("quarter", Value.newBuilder().setStringValue("Q4").build()) .build(); ArrayList indices3 = new ArrayList<>(Arrays.asList( 8661920L, 350356213L, 391213188L, 554637446L, 1024951234L, 1640781426L, 1780689102L, 1799010313L, 2194093370L, 2632344667L, 2641553256L, 2779594451L, 3517203014L, 3543799498L, 3837503950L, 4283091697L )); ArrayList values3 = new ArrayList<>(Arrays.asList( 2.6875f, 4.2929688f, 3.609375f, 3.0722656f, 2.1152344f, 5.78125f, 3.7460938f, 3.7363281f, 1.2695312f, 3.4824219f, 0.7207031f, 0.0826416f, 4.671875f, 3.7011719f, 2.796875f, 0.61621094f )); Struct sparseMetaData3 = Struct.newBuilder() .putFields("chunk_text", Value.newBuilder().setStringValue("AAPL'\\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production").build()) .putFields("category", Value.newBuilder().setStringValue("technology").build()) .putFields("quarter", Value.newBuilder().setStringValue("Q3").build()) .build(); sparseIndexConnection.upsert("vec1", Collections.emptyList(), indices1, values1, sparseMetaData1, "example-namespace"); sparseIndexConnection.upsert("vec2", Collections.emptyList(), indices2, values2, sparseMetaData2, "example-namespace"); sparseIndexConnection.upsert("vec3", Collections.emptyList(), indices3, values3, sparseMetaData3, "example-namespace"); // Check the number of records each the index DescribeIndexStatsResponse denseIndexStatsResponse = denseIndexConnection.describeIndexStats(null); System.out.println("Index stats (dense):"); System.out.println(denseIndexStatsResponse); DescribeIndexStatsResponse sparseIndexStatsResponse = sparseIndexConnection.describeIndexStats(null); System.out.println("Index stats (sparse):"); System.out.println(sparseIndexStatsResponse); // Query the index (dense) with a metadata filter List queryVector = Arrays.asList(1.0f, 1.5f); QueryResponseWithUnsignedIndices denseQueryResponse = denseIndexConnection.query(1, queryVector, null, null, null, "example-namespace", null, false, true); System.out.println("Dense query response:"); System.out.println(denseQueryResponse); // Query the index (sparse) with a metadata filter List sparseIndices = Arrays.asList( 767227209L, 1640781426L, 1690623792L, 2021799277L, 2152645940L, 2295025838L, 2443437770L, 2779594451L, 2956155693L, 3476647774L, 3818127854L, 428309169L); List sparseValues = Arrays.asList( 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f); QueryResponseWithUnsignedIndices sparseQueryResponse = sparseIndexConnection.query(1, null, sparseIndices, sparseValues, null, "example-namespace", null, false, true); System.out.println("Sparse query response:"); System.out.println(sparseQueryResponse); // Delete the indexes pc.deleteIndex(denseIndexName); pc.deleteIndex(sparseIndexName); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" "google.golang.org/protobuf/types/known/structpb" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() // Initialize a client. // No API key is required. // Host and port of the Pinecone Local instance // is required when starting without indexes. pc, err := pinecone.NewClientBase(pinecone.NewClientBaseParams{ Host: "http://localhost:5080", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // Create two indexes, one dense and one sparse denseIndexName := "dense-index" denseVectorType := "dense" dimension := int32(2) denseMetric := pinecone.Cosine deletionProtection := pinecone.DeletionProtectionDisabled denseIdx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: denseIndexName, VectorType: &denseVectorType, Dimension: &dimension, Metric: &denseMetric, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: &deletionProtection, Tags: &pinecone.IndexTags{"environment": "development"}, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", denseIdx.Name) } else { fmt.Printf("Successfully created serverless index: %v\n", denseIdx.Name) } sparseIndexName := "sparse-index" sparseVectorType := "sparse" sparseMetric := pinecone.Dotproduct sparseIdx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: sparseIndexName, VectorType: &sparseVectorType, Metric: &sparseMetric, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: &deletionProtection, Tags: &pinecone.IndexTags{"environment": "development"}, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", sparseIdx.Name) } else { fmt.Printf("\nSuccessfully created serverless index: %v\n", sparseIdx.Name) } // Get the index hosts denseIdxModel, err := pc.DescribeIndex(ctx, denseIndexName) if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", denseIndexName, err) } sparseIdxModel, err := pc.DescribeIndex(ctx, sparseIndexName) if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", sparseIndexName, err) } // Target the indexes. // Make sure to prefix the hosts with http:// to let the SDK know to disable tls. denseIdxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "http://" + denseIdxModel.Host, Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } sparseIdxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "http://" + sparseIdxModel.Host, Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } // Upsert records into the index (dense) denseMetadataMap1 := map[string]interface{}{ "genre": "drama", } denseMetadata1, err := structpb.NewStruct(denseMetadataMap1) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } denseMetadataMap2 := map[string]interface{}{ "genre": "documentary", } denseMetadata2, err := structpb.NewStruct(denseMetadataMap2) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } denseMetadataMap3 := map[string]interface{}{ "genre": "documentary", } denseMetadata3, err := structpb.NewStruct(denseMetadataMap3) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } denseVectors := []*pinecone.Vector{ { Id: "vec1", Values: &[]float32{1.0, -2.5}, Metadata: denseMetadata1, }, { Id: "vec2", Values: &[]float32{3.0, -2.0}, Metadata: denseMetadata2, }, { Id: "vec3", Values: &[]float32{0.5, -1.5}, Metadata: denseMetadata3, }, } denseCount, err := denseIdxConnection.UpsertVectors(ctx, denseVectors) if err != nil { log.Fatalf("Failed to upsert vectors: %v", err) } else { fmt.Printf("\nSuccessfully upserted %d vector(s)!\n", denseCount) } // Upsert records into the index (sparse) sparseValues1 := pinecone.SparseValues{ Indices: []uint32{822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191}, Values: []float32{1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688}, } sparseMetadataMap1 := map[string]interface{}{ "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones", "category": "technology", "quarter": "Q3", } sparseMetadata1, err := structpb.NewStruct(sparseMetadataMap1) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } sparseValues2 := pinecone.SparseValues{ Indices: []uint32{131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697}, Values: []float32{0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.560546}, } sparseMetadataMap2 := map[string]interface{}{ "chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4", } sparseMetadata2, err := structpb.NewStruct(sparseMetadataMap2) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } sparseValues3 := pinecone.SparseValues{ Indices: []uint32{8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697}, Values: []float32{2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094}, } sparseMetadataMap3 := map[string]interface{}{ "chunk_text": "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", "category": "technology", "quarter": "Q3", } sparseMetadata3, err := structpb.NewStruct(sparseMetadataMap3) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } sparseVectors := []*pinecone.Vector{ { Id: "vec1", SparseValues: &sparseValues1, Metadata: sparseMetadata1, }, { Id: "vec2", SparseValues: &sparseValues2, Metadata: sparseMetadata2, }, { Id: "vec3", SparseValues: &sparseValues3, Metadata: sparseMetadata3, }, } sparseCount, err := sparseIdxConnection.UpsertVectors(ctx, sparseVectors) if err != nil { log.Fatalf("Failed to upsert vectors: %v", err) } else { fmt.Printf("\nSuccessfully upserted %d vector(s)!\n", sparseCount) } // Check the number of records in each index denseStats, err := denseIdxConnection.DescribeIndexStats(ctx) if err != nil { log.Fatalf("Failed to describe index: %v", err) } else { fmt.Printf("\nIndex stats (dense): %+v\n", prettifyStruct(*denseStats)) } sparseStats, err := sparseIdxConnection.DescribeIndexStats(ctx) if err != nil { log.Fatalf("Failed to describe index: %v", err) } else { fmt.Printf("\nIndex stats (sparse): %+v\n", prettifyStruct(*sparseStats)) } // Query the index (dense) with a metadata filter queryVector := []float32{3.0, -2.0} queryMetadataMap := map[string]interface{}{ "genre": map[string]interface{}{ "$eq": "documentary", }, } metadataFilter, err := structpb.NewStruct(queryMetadataMap) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } denseRes, err := denseIdxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{ Vector: queryVector, TopK: 1, MetadataFilter: metadataFilter, IncludeValues: false, IncludeMetadata: true, }) if err != nil { log.Fatalf("Error encountered when querying by vector: %v", err) } else { fmt.Printf("\nDense query response: %v\n", prettifyStruct(denseRes)) } // Query the index (sparse) with a metadata filter sparseValues := pinecone.SparseValues{ Indices: []uint32{767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697}, Values: []float32{1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0}, } sparseRes, err := sparseIdxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{ SparseValues: &sparseValues, TopK: 1, IncludeValues: false, IncludeMetadata: true, }) if err != nil { log.Fatalf("Error encountered when querying by vector: %v", err) } else { fmt.Printf("\nSparse query response: %v\n", prettifyStruct(sparseRes)) } // Delete the indexes err = pc.DeleteIndex(ctx, denseIndexName) if err != nil { log.Fatalf("Failed to delete index: %v", err) } else { fmt.Printf("\nIndex \"%v\" deleted successfully\n", denseIndexName) } err = pc.DeleteIndex(ctx, sparseIndexName) if err != nil { log.Fatalf("Failed to delete index: %v", err) } else { fmt.Printf("\nIndex \"%v\" deleted successfully\n", sparseIndexName) } } ``` ```shell curl theme={null} PINECONE_LOCAL_HOST="localhost:5080" DENSE_INDEX_HOST="localhost:5081" SPARSE_INDEX_HOST="localhost:5082" # Create two indexes, one dense and one sparse curl -X POST "http://$PINECONE_LOCAL_HOST/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "dense-index", "vector_type": "dense", "dimension": 2, "metric": "cosine", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "tags": { "environment": "development" }, "deletion_protection": "disabled" }' curl -X POST "http://$PINECONE_LOCAL_HOST/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "sparse-index", "vector_type": "sparse", "metric": "dotproduct", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "tags": { "environment": "development" }, "deletion_protection": "disabled" }' # Upsert records into the index (dense) curl -X POST "http://$DENSE_INDEX_HOST/vectors/upsert" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "namespace": "example-namespace", "vectors": [ { "id": "vec1", "values": [1.0, -2.5], "metadata": {"genre": "drama"} }, { "id": "vec2", "values": [3.0, -2.0], "metadata": {"genre": "documentary"} }, { "id": "vec3", "values": [0.5, -1.5], "metadata": {"genre": "documentary"} } ] }' # Upsert records into the index (sparse) curl -X POST "http://$SPARSE_INDEX_HOST/vectors/upsert" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "namespace": "example-namespace", "vectors": [ { "id": "vec1", "sparseValues": { "values": [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688], "indices": [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191] }, "metadata": { "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "category": "technology", "quarter": "Q3" } }, { "id": "vec2", "sparseValues": { "values": [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469], "indices": [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697] }, "metadata": { "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4" } }, { "id": "vec3", "sparseValues": { "values": [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094], "indices": [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697] }, "metadata": { "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", "category": "technology", "quarter": "Q3" } } ] }' # Check the number of records in each index curl -X POST "http://$DENSE_INDEX_HOST/describe_index_stats" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{}' curl -X POST "http://$SPARSE_INDEX_HOST/describe_index_stats" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{}' # Query the index (dense) with a metadata filter curl "http://$DENSE_INDEX_HOST/query" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "vector": [3.0, -2.0], "filter": {"genre": {"$eq": "documentary"}}, "topK": 1, "includeMetadata": true, "includeValues": false, "namespace": "example-namespace" }' # Query the index (sparse) with a metadata filter curl "http://$SPARSE_INDEX_HOST/query" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "sparseVector": { "values": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0], "indices": [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697] }, "filter": {"quarter": {"$eq": "Q4"}}, "namespace": "example-namespace", "topK": 1, "includeMetadata": true, "includeValues": false }' # Delete the index curl -X DELETE "http://$PINECONE_LOCAL_HOST/indexes/dense-index" \ -H "X-Pinecone-Api-Version: 2025-10" curl -X DELETE "http://$PINECONE_LOCAL_HOST/indexes/sparse-index" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ## 3. Stop Pinecone Local Pinecone Local is an in-memory emulator. Records loaded into Pinecone Local do not persist after Pinecone Local is stopped. To stop and remove the resources for Pinecone Local, run the following command: ```shell Docker Compose theme={null} docker compose down ``` ```shell Docker CLI theme={null} # If you started Pinecone Local with indexes: docker stop dense-index sparse-index docker rm dense-index sparse-index # If you started Pinecone Local without indexes: docker stop pinecone-local docker rm pinecone-local ``` ## Moving from Pinecone Local to your Pinecone account When you're ready to run your application against your Pinecone account, be sure to do the following: * Update your application to [use your Pinecone API key](/reference/api/authentication). * Update your application to [target your Pinecone indexes](/guides/manage-data/target-an-index). * [Use Pinecone's import feature](/guides/index-data/import-data) to efficiently load large amounts of data into your indexes and then [use batch upserts](/guides/index-data/upsert-data#upsert-in-batches) for ongoing writes. * Follow Pinecone's [production best practices](/guides/production/production-checklist). # Use the Pinecone MCP server Source: https://docs.pinecone.io/guides/operations/mcp-server Connect AI agents to Pinecone through the MCP server to search docs, manage indexes, and query data from Claude, Cursor, Antigravity, or Claude Code. The Pinecone MCP server enables AI agents to interact directly with Pinecone's functionality and documentation via the standardized [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). Using the MCP server, agents can search Pinecone documentation, manage indexes, upsert data, and query indexes for relevant information. This page shows you how to configure [Antigravity](https://antigravity.google/), [Claude Desktop](https://claude.ai/download), [Claude Code](https://claude.ai/code), and [Cursor](https://www.cursor.com/) to connect with the Pinecone MCP server. Pinecone also provides a dedicated MCP server for each [Pinecone Assistant](/guides/assistant/overview), giving AI agents direct access to context from that assistant's uploaded files. The assistant MCP server is available as a managed remote endpoint or as a self-hosted Docker container that you can extend and run in your own infrastructure. See [Use an Assistant MCP server](/guides/assistant/mcp-server). Pinecone also offers plugins and extensions with built-in skills for agentic IDEs and CLIs. See [Agentic IDEs and CLIs](/guides/get-started/ai-coding-tools) for an overview, or jump directly to the [Claude Code plugin](/integrations/claude-code), [Gemini CLI extension](/integrations/gemini-cli), [Cursor plugin](/integrations/cursor), or [Agent Skills](/integrations/agent-skills) for GitHub Copilot and other IDEs. ## Tools The Pinecone MCP server provides the following tools: * `search-docs`: Search the official Pinecone documentation. * `list-indexes`: Lists all Pinecone indexes. * `describe-index`: Describes the configuration of an index. * `describe-index-stats`: Provides statistics about the data in the index, including the number of records and available namespaces. * `create-index-for-model`: Creates a new index that uses an integrated inference model to embed text as vectors. * `upsert-records`: Inserts or updates records in an index with integrated inference. * `search-records`: Searches for records in an index based on a text query, using integrated inference for embedding. Has options for metadata filtering and reranking. * `cascading-search`: Searches for records across multiple indexes, deduplicating and reranking the results. * `rerank-documents`: Reranks a collection of records or text documents using a specialized reranking model. The Pinecone MCP supports only [indexes with integrated embedding](/guides/index-data/indexing-overview#vector-embedding). Indexes for vectors you create with external embedding models are not supported. ## Before you begin Ensure you have the following: * A [Pinecone API key](https://app.pinecone.io/organizations/-/keys) * [Node.js](https://nodejs.org/en) installed, with `node` and `npx` available on your `PATH` ## Configure Antigravity Antigravity supports MCP via its built-in MCP Store. You can install the Pinecone server from the store or add it via the raw config. **Install from the MCP Store** 1. Open the **MCP Store** via the "..." dropdown at the top of the editor's agent panel. 2. Find **Pinecone** in the list of supported servers and click **Install**. 3. Follow the on-screen prompts to authenticate and set your Pinecone API key. **Add via raw config** 1. Open the MCP Store via the "..." dropdown at the top of the editor's agent panel. 2. Click **Manage MCP Servers**, then **View raw config**. 3. Edit `mcp_config.json` and add the Pinecone server: ```json theme={null} { "mcpServers": { "pinecone": { "command": "npx", "args": [ "-y", "@pinecone-database/mcp" ], "env": { "PINECONE_API_KEY": "{{YOUR_API_KEY}}" } } } } ``` Replace `YOUR_API_KEY` with your [Pinecone API key](https://app.pinecone.io/organizations/-/keys). After installing or saving the config, the Pinecone server and its tools should appear in the agent panel. Use the MCP tools list to confirm the server is connected. In the agent chat, try prompts that use Pinecone. For example, try generating code that creates an index, upserts records, or searches the index. The AI can use the connected MCP server for context and actions. ## Configure Claude Code For the easiest setup, install the [Pinecone Claude Code plugin](/integrations/claude-code) instead — it bundles the MCP server, 8 skills, and slash commands. The manual configuration below is for users who only want the MCP server. Run the following command to add the Pinecone MCP server to your Claude Code instance: ```bash theme={null} claude mcp add-json pinecone-mcp \ '{"type": "stdio", "command": "npx", "args": ["-y", "@pinecone-database/mcp"], "env": {"PINECONE_API_KEY": "YOUR_API_KEY"}}' ``` Restart Claude Code. Then, run the `/mcp` command to check the status of the Pinecone MCP. You should see the following: ```bash theme={null} > /mcp ⎿ MCP Server Status • pinecone-mcp: ✓ connected ``` Test the Pinecone MCP server with prompts to Claude Code that require the server to generate Pinceone-compatible code and perform tasks in your Pinecone account. Generate code: > Write a Python script that creates an index for dense vectors with integrated embedding, upserts 20 sentences about dogs, waits 10 seconds, searches the index, and reranks the results. Perform tasks: > Create an index for dense vectors with integrated embedding, upsert 20 sentences about dogs, waits 10 seconds, search the index, and reranks the results. ## Configure Claude Desktop Go to **Settings > Developer > Edit Config** and add the following configuration: ```json theme={null} { "mcpServers": { "pinecone": { "command": "npx", "args": [ "-y", "@pinecone-database/mcp" ], "env": { "PINECONE_API_KEY": "YOUR_API_KEY" } } } } ``` Replace `YOUR_API_KEY` with your Pinecone API key. Restart Claude Desktop. On the new chat screen, you should see a hammer (MCP) icon appear with the new MCP tools available. Test the Pinecone MCP server with prompts that required the server to generate Pinceone-compatible code and perform tasks in your Pinecone account. Generate code: > Write a Python script that creates an index for dense vectors with integrated embedding, upserts 20 sentences about dogs, waits 10 seconds, searches the index, and reranks the results. Perform tasks: > Create an index for dense vectors with integrated embedding, upsert 20 sentences about dogs, waits 10 seconds, search the index, and reranks the results. ## Configure Cursor For the easiest setup, install the [Pinecone Cursor plugin](/integrations/cursor) instead — it bundles the MCP server, 8 skills, and slash commands. The manual configuration below is for users who only want the MCP server. In your project root, create a `.cursor/mcp.json` file, if it doesn't exist, and add the following configuration: ```json theme={null} { "mcpServers": { "pinecone": { "command": "npx", "args": [ "-y", "@pinecone-database/mcp" ], "env": { "PINECONE_API_KEY": "{{YOUR_API_KEY}}" } } } } ``` Go to **Cursor Settings > MCP**. You should see the server and its list of tools. The Pinecone MCP server works well out of the box. However, you can add explicit rules to ensure the server behaves as you expect. In your project root, create a `.cursor/rules/pinecone.mdc` file and add the following: ```mdx [expandable] theme={null} ### Tool Usage for Code Generation - When generating code related to Pinecone, always use the `pinecone` MCP and the `search_docs` tool. - Perform at least two distinct searches per request using different, relevant questions to ensure comprehensive context is gathered before writing code. ### Error Handling - If an error occurs while executing Pinecone-related code, immediately invoke the `pinecone` MCP and the `search_docs` tool. - Search for guidance on the specific error encountered and incorporate any relevant findings into your resolution strategy. ### Syntax and Version Accuracy - Before writing any code, verify and use the correct syntax for the latest stable version of the Pinecone SDK. - Prefer official code snippets and examples from documentation over generated or assumed field values. - Do not fabricate field names, parameter values, or request formats. ### SDK Installation Best Practices - When providing installation instructions, always reference the current official package name. - For Pinecone, use `pip install pinecone` not deprecated packages like `pinecone-client`. ``` Press `Command + i` to open the Agent chat. Test the Pinecone MCP server with prompts that required the server to generate Pinceone-compatible code and perform tasks in your Pinecone account. Generate code: > Write a Python script that creates an index for dense vectors with integrated embedding, upserts 20 sentences about dogs, waits 10 seconds, searches the index, and reranks the results. Perform tasks: > Create an index for dense vectors with integrated embedding, upsert 20 sentences about dogs, waits 10 seconds, search the index, and reranks the results. # Decrease latency Source: https://docs.pinecone.io/guides/optimize/decrease-latency Reduce query and upsert latency in Pinecone using namespaces, metadata filters, targeting indexes by host, and regional colocation strategies. ## Use namespaces When you divide records into [namespaces](/guides/index-data/indexing-overview#namespaces) in a logical way, you speed up queries by ensuring only relevant records are scanned. The same applies to [fetching records](/guides/manage-data/fetch-data), [listing record IDs](/guides/manage-data/list-record-ids), and other data operations. ## Filter by metadata In addition to increasing search accuracy and relevance, [searching with metadata filters](/guides/search/filter-by-metadata) can also help decrease latency by retrieving only records that match the filter. ## Target indexes by host When you target an index by name for data operations such as `upsert` and `query`, the SDK gets the unique DNS host for the index using the `describe_index` operation. This is convenient for testing but should be avoided in production because `describe_index` uses a different API than data operations and therefore adds an additional network call and point of failure. Instead, you should get an index host once and cache it for reuse or specify the host directly. You can get index hosts in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes) or using the [`describe_index`](/guides/manage-data/manage-indexes#describe-an-index) operation. The following example shows how to target an index by host directly: When using Private Endpoints for private connectivity between your application and Pinecone, you must target the index using the [Private Endpoint URL](/guides/production/configure-private-endpoints#read-and-write-data) for the host. ```Python Python {5} theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index(host="INDEX_HOST") ``` ```javascript JavaScript {6} theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); // For the Node.js SDK, you must specify both the index host and name. const index = pc.index("INDEX_NAME", "INDEX_HOST"); ``` ```java Java {11} theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; public class TargetIndexByHostExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); // For the Java SDK, you must specify both the index host and name. Index index = new Index(connection, "INDEX_NAME"); } } ``` ```go Go {21} theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host %v: %v", idx.Host, err) } } ``` ## Reuse connections When you target an index for upserting or querying, the client establishes a TCP connection, which is a three-step process. To avoid going through this process on every request, and reduce average request latency, [cache and reuse the index connection object](/reference/api/authentication#initialize-a-client) whenever possible. ## Use a cloud environment If you experience slow uploads or high query latencies, it might be because you are accessing Pinecone from your home network. To decrease latency, access Pinecone/deploy your application from a cloud environment instead, ideally from the same [cloud and region](/guides/index-data/create-an-index#cloud-regions) as your index. ## Avoid batching queries If you're batching queries, try reducing the number of queries per call to a single query vector. You can run these [queries in parallel](/guides/search/semantic-search#parallel-queries) and expect roughly the same performance as with batching. ## Avoid including vector values when not needed Including vector values increases response size -- especially with higher `top_k` values —- which can elevate round-trip latency. If you don't need the vector values in your response, set `include_values=false` to improve query performance. This applies to [`query`](/reference/api/latest/data-plane/query) and [`fetch`](/reference/api/latest/data-plane/fetch) operations. On-demand indexes retrieve vector values from object storage, so `fetch` operations and queries with `include_values=true` may occasionally experience higher tail latency before values are cached on disk. DRN indexes cache values locally and are not affected. ## Work with database limits Pinecone has [rate limits](/reference/api/database-limits#rate-limits) to protect your applications and maintain infrastructure health. Rate limits vary based on pricing plan and apply to serverless indexes only. Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. To handle rate limits effectively: * [Implement retry logic with exponential backoff](/guides/production/error-handling#handle-rate-limits-429). * If you need higher limits for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Most limits can be adjusted to accommodate your scaling needs. # Increase search relevance Source: https://docs.pinecone.io/guides/optimize/increase-relevance Improve Pinecone search quality with reranking models, metadata filtering, and hybrid search that combines full-text and vector retrieval for RAG. This page describes helpful techniques for improving search accuracy and relevance. ## Rerank results [Reranking](/guides/search/rerank-results) is used as part of a two-stage vector retrieval process to improve the quality of results. You first query an index for a given number of relevant results, and then you send the query and results to a reranking model. The reranking model scores the results based on their semantic relevance to the query and returns a new, more accurate ranking. This approach is one of the simplest methods for improving quality in retrieval augmented generation (RAG) pipelines. Pinecone provides [hosted reranking models](/guides/search/rerank-results#reranking-models) so it's easy to manage two-stage vector retrieval on a single platform. You can use a hosted model to rerank results as an integrated part of a query, or you can use a hosted model to rerank results as a standalone operation. ## Filter by metadata Every [record](/guides/get-started/concepts#record) in an index must contain an ID and a dense or sparse vector, depending on the [type of index](/guides/index-data/indexing-overview#indexes). In addition, you can include metadata key-value pairs to store related information or context. When you search the index, you can then include a metadata filter to limit the search to records matching a filter expression. For example, if an index contains records about books, you could use a metadata field to associate each record with a genre, like `"genre": "fiction"` or `"genre": "poetry"`. When you query the index, you could then use a metadata filter to limit your search to records related to a specific genre. For more details, see [Filter by metadata](/guides/search/filter-by-metadata). ## Use full-text search for keyword matching When relevance depends on exact keyword or phrase matches over text content — for example, product names, technical IDs, named entities, or jargon — we recommend [full-text search](/guides/search/full-text-search). It uses **BM25** ranking on `string` fields you've declared with `full_text_search` enabled and supports Lucene query syntax (`query_string`), including phrase, boolean, and proximity operators, plus the `$match_phrase` filter for exact phrase matching against text fields. An index with a document schema can also include `dense_vector` and `sparse_vector` fields in the same schema, so you can combine BM25 token matching with semantic or sparse-vector ranking on a single index. A single search request ranks by one scoring type — restrict a `dense_vector` or `sparse_vector` search with a text-match filter (`$match_phrase`, `$match_all`, `$match_any`) on an FTS-enabled `string` field, or run BM25 and dense (or sparse) searches separately and merge the results client-side. For more details, see [Full-text search](/guides/search/full-text-search). ## Match the query and passage embedding paths When you use [integrated embedding](/guides/index-data/indexing-overview#integrated-embedding) with a model like [`llama-text-embed-v2`](/models/llama-text-embed-v2) or [`multilingual-e5-large`](/models/multilingual-e5-large), Pinecone embeds upserted data with the `passage` input type and embeds query text with the `query` input type. The encoder is the same, but the input type changes the resulting vector, so the *same* string embedded as a query and as a passage produces two different vectors. This is intentional in E5- and Llama-style models: the asymmetry is what makes a short query match a longer, semantically related passage. A common consequence is that searching by text for the exact string you upserted does not return a similarity score near `1.0`. For example, querying for the exact text `"JetBlue Flights and Extras"` against a record containing that same text can score around `0.58`, while searching by the raw passage vector for the same record scores near `1.0`. The text query takes the `query` path and the stored record was embedded via the `passage` path, so the two vectors are not identical. **Is a low score expected for identical short strings?** Yes. The query/passage split has the largest effect on short, low-semantic text such as exact names, error codes, SKUs, and IDs, where there is little meaning for the model to align across the two paths. Scores in roughly the `0.5`–`0.8` range for identical short strings are normal. The asymmetry helps on true semantic search (a short question matched to a longer answer passage) and only looks like a problem on exact-token-match workloads. **When should you query through the passage path?** Only when the workload is exact or near-exact lookup (IDs, error logs, product names) rather than semantic search, and you want exact matches to score near `1.0`. You can override the read-time input type at the index level with [`configure_index`](/reference/api/latest/control-plane/configure_index). Set `model` and `field_map` to the index's existing values, and set `read_parameters.input_type` to `passage`: ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.configure_index( name="docs-example", embed={ "model": "llama-text-embed-v2", "field_map": {"text": "chunk_text"}, "read_parameters": {"input_type": "passage"} } ) ``` Note the trade-offs: * This setting degrades true semantic search, since queries no longer use the input type the model was trained to expect. * It applies to the whole index. With integrated inference you cannot choose `query` or `passage` per request. If you need that control, embed text yourself with the [Inference API](/reference/api/latest/inference/generate-embeddings) and search with the [`query`](/reference/api/latest/data-plane/query) operation using your own vectors. For pure exact-match retrieval, a [sparse index](/guides/index-data/indexing-overview#indexes-with-sparse-vectors) or [full-text search](/guides/search/full-text-search) is usually a better fit than forcing dense embeddings through the passage path. See [Use full-text search for keyword matching](#use-full-text-search-for-keyword-matching) above for when keyword and phrase matching is the right tool. ## Use hybrid search When you have both dense and sparse vectors for the same records and want to combine semantic and lexical signals at query time, you can use hybrid search. [Semantic search](/guides/search/semantic-search) can miss results based on exact keyword matches, especially in scenarios involving domain-specific terminology, while sparse-vector [lexical search](/guides/search/lexical-search) can miss results based on relationships, such as synonyms and paraphrases. Hybrid search combines the two. There are two ways to do this: * [Use a single index for dense and sparse vectors](/guides/search/hybrid-search#use-a-single-index-for-dense-and-sparse-vectors). This is the **recommended** approach for most use cases because you make requests to a single index, the linkage between dense and sparse vectors is implicit, and you can perform hybrid queries with a single request. Note that you'll need to [normalize sparse and dense values](/guides/search/hybrid-search#normalize-sparse-and-dense-values) at query time so the unbounded sparse component doesn't dominate the combined score. * [Use separate indexes for dense and sparse vectors](/guides/search/hybrid-search#use-separate-indexes-for-dense-and-sparse-vectors). This approach provides more flexibility but requires managing two indexes, maintaining linkages between vectors, and querying each index separately before merging results. If you'd rather not tune sparse and dense weights at all, an [index with a document schema](/guides/get-started/concepts#document) with a multi-field schema is a simpler single-index alternative: declare FTS-enabled `string` fields alongside a `dense_vector` or `sparse_vector` field on the same index, then either restrict the dense (or sparse) search with a text-match filter on the lexical field, or run separate searches and merge the results client-side. For more details, including guidance on choosing the right approach, see [Hybrid search](/guides/search/hybrid-search). ## Explore chunking strategies You can chunk your content in different ways to get better results. Consider factors like the length of the content, the complexity of queries, and how results will be used in your application. For more details, see [Chunking strategies](https://www.pinecone.io/learn/chunking-strategies/). # Increase throughput Source: https://docs.pinecone.io/guides/optimize/increase-throughput Increase Pinecone throughput with bulk import from object storage, batch upserts, parallel requests, and the Python gRPC SDK for faster ingestion. ## Import from object storage [Importing from object storage](/guides/index-data/import-data) is the most efficient and cost-effective method to load large numbers of records into an index. You store your data as Parquet files in object storage, integrate your object storage with Pinecone, and then start an asynchronous, long-running operation that imports and indexes your records. ## Upsert in batches [Upserting in batches](/guides/index-data/upsert-data#upsert-in-batches) is another efficient way to ingest large numbers of records (up to 1000 per batch). Batch upserting is also a good option if you cannot work around bulk import's current [limitations](/guides/index-data/import-data#import-limits). ## Upsert/search in parallel Pinecone is thread-safe, so you can send multiple [upsert](/guides/index-data/upsert-data#upsert-in-parallel) requests and multiple [query](/guides/search/semantic-search#parallel-queries) requests in parallel to help increase throughput. ## Python SDK options ### Use gRPC Use the [Python SDK with gRPC extras](/reference/sdks/python/overview) to run data operations such as upserts and queries over [gRPC](https://grpc.io/) rather than HTTP for a modest performance improvement. ### Upsert from a dataframe To quickly ingest data when using the Python SDK, use the [`upsert_from_dataframe` method](/reference/sdks/python/overview#upsert-from-a-dataframe). The method includes retry logic and `batch_size`, and is performant especially with Parquet file data sets. ## See also Read more about [high-throughput optimizations](https://www.pinecone.io/blog/working-at-scale/) on our blog. # Save on costs Source: https://docs.pinecone.io/guides/optimize/save-on-costs Save on Pinecone costs by using bulk import over upsert, namespaces for multitenancy, and query patterns that reduce read unit consumption. ## Credits and discounts In addition to the workload optimizations below, you can lower your effective rate: * **Prepaid credits and annual commitments** earn discounted usage rates. See [Prepaid credits](/guides/manage-cost/understanding-cost#prepaid-credits). * **One-time bulk import credit.** Standard and Enterprise organizations receive a one-time 1 TB credit for [importing data from object storage](/guides/manage-cost/understanding-cost#imports). * **Dedicated read nodes** can lower cost for sustained, high read throughput when you fully use the provisioned capacity (see [Choose the right index capacity mode](#choose-the-right-index-capacity-mode)). * **Volume discounts.** Standard and Enterprise customers can [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) to discuss cost optimization and discounts. ## Prefer bulk import over upsert for large loads When you need to populate a new namespace or load a large dataset (for example, millions of records or hundreds of GB), [importing from object storage](/guides/index-data/import-data) is usually the most efficient and cost-effective path compared to streaming [upserts](/guides/index-data/upsert-data). * **Import** is optimized for one-time or bulk loads from Parquet in your object store and is priced based on data read during the job. See [Import cost](/guides/manage-cost/understanding-cost#imports). * **Upsert** is priced in write units based on request size; many small requests can cost more than fewer large ones for the same total data. See [Write unit pricing](/guides/manage-cost/understanding-cost#write-units). Use upsert (including [batch upsert](/guides/index-data/upsert-data#upsert-in-batches)) for ongoing, incremental ingestion after your initial load. For how import and upsert compare, see the [data ingestion overview](/guides/index-data/data-ingestion-overview). Partitioning tenants with [namespaces](/guides/index-data/implement-multitenancy) instead of many separate indexes often lowers storage overhead and query cost, because cost depends in part on how much data each query scans. For patterns and rationale, see [Manage cost](/guides/manage-cost/manage-cost#use-namespaces-for-multitenancy). ## Right-size reads and queries * Avoid returning vector values in read responses when you do not need them (`include_values=false`), especially at high `top_k`. Values are typically the largest part of a response, so omitting them lowers [egress](/guides/manage-cost/understanding-cost#egress) and helps you stay within your plan's egress allowance. * Use [metadata filters](/guides/search/filter-by-metadata) so queries scan fewer records where your workload allows. Omitting values lowers egress, not [read units](/guides/manage-cost/understanding-cost#read-units): query read unit cost depends on the size of the namespace scanned, not on the size of the response. Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ## Choose the right index capacity mode For sustained, high read throughput, [dedicated read nodes](/guides/index-data/dedicated-read-nodes) can be more cost-effective than on-demand when you fully utilize provisioned read capacity. For spiky or low-QPS workloads, on-demand may be cheaper. See [When to use dedicated read nodes](/guides/index-data/dedicated-read-nodes#when-to-use-dedicated-read-nodes) and [Understanding cost](/guides/manage-cost/understanding-cost). ## See also * [Decrease latency](/guides/optimize/decrease-latency) * [Increase throughput](/guides/optimize/increase-throughput) * [Manage cost](/guides/manage-cost/manage-cost) # Access your invoices Source: https://docs.pinecone.io/guides/organizations/manage-billing/access-your-invoices View and download your Pinecone organization billing invoices in the console, including invoice history, receipts, and payment records. You can access your billing history and invoices in the Pinecone console: 1. Go to [**Settings > Billing > Overview**](https://app.pinecone.io/organizations/-/settings/billing). 2. Scroll down to the **Payment history and invoices** section. 3. For each billing period, you can download the invoice by clicking the **Download** button. Each invoice includes line items for the services used during the billing period. If the total cost of that usage is below the monthly minimum, the invoice also includes a line item covering the rest of the minimum usage commitment. # Change your payment method Source: https://docs.pinecone.io/guides/organizations/manage-billing/change-payment-method Update your Pinecone organization payment method in the console, including credit card details, billing address, and payment preferences. You can pay for the [Standard and Enterprise plans](https://www.pinecone.io/pricing/) with a credit/debit card or through the AWS Marketplace, Microsoft Marketplace, or Google Cloud Marketplace. This page describes how to switch between these payment methods. To change your payment method, you must be an [organization owner or billing admin](/guides/organizations/understanding-organizations#organization-roles). The [Builder plan](https://www.pinecone.io/pricing/) is available with credit/debit card billing only and is not supported through cloud marketplaces. To switch a Builder-plan organization to marketplace billing, first [upgrade to the Standard or Enterprise plan](/guides/organizations/manage-billing/upgrade-billing-plan) using the marketplace subscription flow. ## Credit card → marketplace To change from credit card to marketplace billing, you'll need to: 1. Create a new Pinecone organization through the marketplace 2. Migrate your existing projects to the new Pinecone organization 3. Add your team members to the new Pinecone organization 4. Downgrade your original Pinecone organization once migration is complete To change from paying with a credit card to paying through the Google Cloud Marketplace, do the following: 1. Subscribe to Pinecone in the Google Cloud Marketplace: 1. In the Google Cloud Marketplace, go to the [Pinecone listing](https://console.cloud.google.com/marketplace/product/pinecone-public/pinecone). 2. Click **Subscribe**. 3. On the **Order Summary** page, select a billing account, accept the terms and conditions, and click **Subscribe**. The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details. 4. On the **Your order request has been sent to Pinecone** modal, click **Sign up with Pinecone**. This takes you to a Google-specific Pinecone sign-up page. 5. Sign up using the same authentication method as your existing Pinecone organization. 2. Create a new Pinecone organization and connect it to your Google Cloud Marketplace account: 1. On the **Connect GCP to Pinecone** page, choose **Select an organization > + Create New Organization**. If you see a message saying that the subscription is still in process, wait a few minutes, refresh the page, and proceed only when the message has disappeared. 2. Enter the name of the new organization and click **Connect to Pinecone**. 3. On the **Confirm GCP marketplace Connection** modal, click **Connect**. This takes you to your new organization in the Pinecone console. 3. Migrate your projects to the new Pinecone organization: 1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members). 2. Make sure the **Owner** email address for your original organization is set as an **Owner** or **Billing Admin** for your new organization. This allows Pinecone to verify that both the original and new organizations are owned by the same person. 3. Go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage) and copy your new organization ID. 4. Go to [**Settings > Support > Tickets**](https://app.pinecone.io/organizations/-/settings/support/ticket/create). 5. For **Ticket category**, select **Project or Organization Management**. 6. For **Subject**, enter "Migrate projects to a new organization". 7. For **Description**, enter the following: ``` I am changing my payment method from credit card to Google Cloud Marketplace. Please migrate my projects to my new organization: `` ``` 8. Click **Submit**. 4. Add your team members to the new organization: 1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members). 2. [Add your team members to the new organization](/guides/organizations/manage-organization-members#add-a-member-to-an-organization). 5. Downgrade your original Pinecone organization: Do not downgrade your original organization until you receive a confirmation that Pinecone has finished the migration to your new organization. 1. In the Pinecone console, go to your original organization. 2. Go to **Settings > Billing > Plans**. 3. In the **Starter** section, click **Downgrade**. 4. Click **Confirm downgrade**. Going forward, your usage of Pinecone will be billed through the Google Cloud Marketplace. You can [delete your original organization](/troubleshooting/delete-your-organization). However, before deleting, make sure to [download your past invoices](/guides/organizations/manage-billing/access-your-invoices) since you will lose access to them once the organization is deleted. To change from paying with a credit card to paying through the AWS Marketplace, do the following: 1. Subscribe to Pinecone in the AWS Marketplace: 1. In the AWS Marketplace, go to the [Pinecone listing](https://aws.amazon.com/marketplace/pp/prodview-xhgyscinlz4jk). 2. Click **View purchase options**. 3. On the **Subscribe to Pinecone Vector Database** page, review the offer and then click **Subscribe**. The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details. 4. You'll see a message stating that your subscription is in process. Click **Set up your account**. This takes you to an AWS-specific Pinecone sign-up page. 5. Sign up using the same authentication method as your existing Pinecone organization. 2. Create a new Pinecone organization and connect it to your AWS account: 1. On the **Connect AWS to Pinecone** page, choose **Select an organization > + Create New Organization**. If you see a message saying that the subscription is still in process, wait a few minutes, refresh the page, and proceed only when the message has disappeared. 1. Enter the name of the new organization and click **Connect to Pinecone**. 2. On the **Confirm AWS Marketplace Connection** modal, click **Connect**. This takes you to your new organization in the Pinecone console. 3. Migrate your projects to the new Pinecone organization: 1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members). 2. Make sure the **Owner** email address for your original organization is set as an **Owner** or **Billing Admin** for your new organization. This allows Pinecone to verify that both the original and new organizations are owned by the same person. 3. Go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage) and copy your new organization ID. 4. Go to [**Settings > Support > Tickets**](https://app.pinecone.io/organizations/-/settings/support/ticket/create). 5. For **Ticket category**, select **Project or Organization Management**. 6. For **Subject**, enter "Migrate projects to a new organization". 7. For **Description**, enter the following: ``` I am changing my payment method from credit card to Google Cloud Marketplace. Please migrate my projects to my new organization: `` ``` 8. Click **Submit**. 4. Add your team members to the new organization: 1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members). 2. [Add your team members to the new organization](/guides/organizations/manage-organization-members#add-a-member-to-an-organization). 5. Downgrade your original Pinecone organization: Do not downgrade your original organization until you receive a confirmation that Pinecone has finished the migration to your new organization. 1. In the Pinecone console, go to your original organization. 2. Go to **Settings > Billing > Plans**. 3. In the **Starter** section, click **Downgrade**. 4. Click **Confirm downgrade**. Going forward, your usage of Pinecone will be billed through the AWS Marketplace. You can [delete your original organization](/troubleshooting/delete-your-organization). However, before deleting, make sure to [download your past invoices](/guides/organizations/manage-billing/access-your-invoices) since you will lose access to them once the organization is deleted. To change from paying with a credit card to paying through the Microsoft Marketplace, do the following: 1. Subscribe to Pinecone in the Microsoft Marketplace: 1. In the Microsoft Marketplace, go to the [Pinecone listing](https://marketplace.microsoft.com/product/saas/pineconesystemsinc1688761585469.pineconesaas). 2. Click **Get it now**. 3. Select the **Pinecone - Pay As You Go** plan. 4. Click **Subscribe**. 5. On the **Subscribe to Pinecone** page, select the required details and click **Review + subscribe**. The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details. 6. Click **Subscribe**. 7. After the subscription is approved, click **Configure account now**. This redirects you to an Microsoft-specific Pinecone login page. 8. Sign up using the same authentication method as your existing Pinecone organization. 2. Create a new Pinecone organization and connect it to your Microsoft Marketplace account: 1. On the **Connect Azure to Pinecone** page, choose **Select an organization > + Create New Organization**. If you see a message saying that the subscription is still in process, wait a few minutes, refresh the page, and proceed only when the message has disappeared. 1. Enter the name of the new organization and click **Connect to Pinecone**. 2. On the **Connect Azure marketplace connection** modal, click **Connect**. This takes you to your new organization in the Pinecone console. 3. Migrate your projects to the new Pinecone organization: 1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members). 2. Make sure the **Owner** email address for your original organization is set as an **Owner** or **Billing Admin** for your new organization. This allows Pinecone to verify that both the original and new organizations are owned by the same person. 3. Go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage) and copy your new organization ID. 4. Go to [**Settings > Support > Tickets**](https://app.pinecone.io/organizations/-/settings/support/ticket/create). 5. For **Ticket category**, select **Project or Organization Management**. 6. For **Subject**, enter "Migrate projects to a new organization". 7. For **Description**, enter the following: ``` I am changing my payment method from credit card to Microsoft Marketplace. Please migrate my projects to my new organization: `` ``` 8. Click **Submit**. 4. Add your team members to the new organization: 1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members). 2. [Add your team members to the new organization](/guides/organizations/manage-organization-members#add-a-member-to-an-organization). 5. Downgrade your original Pinecone organization: Do not downgrade your original organization until you receive a confirmation that Pinecone has finished the migration to your new organization. 1. In the Pinecone console, go to your original organization. 2. Go to **Settings > Billing > Plans**. 3. In the **Starter** section, click **Downgrade**. 4. Click **Confirm downgrade**. Going forward, your usage of Pinecone will be billed through the Microsoft Marketplace. You can [delete your original organization](/troubleshooting/delete-your-organization). However, before deleting, make sure to [download your past invoices](/guides/organizations/manage-billing/access-your-invoices) since you will lose access to them once the organization is deleted. ## Marketplace → credit card To change from marketplace billing to credit card, you'll need to: 1. Create a new organization in your Pinecone account 2. Upgrade the new organization to the Standard or Enterprise plan 3. Migrate your existing projects to the new organization 4. Add your team members to the new organization 5. Downgrade your original organization once migration is complete To change from paying through the Google Cloud Marketplace to paying with a credit card, do the following: 1. Create a new organization in your Pinecone account: 1. In the Pinecone console, go to [**Organizations**](https://app.pinecone.io/organizations/-/settings/account/organizations). 2. Click **+ Create organization**. 3. Enter the name of the new organization and click **Create**. 2. Upgrade the new organization: 1. Go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans). 2. Click **Upgrade** in the **Standard** or **Enterprise** plan section. 3. Click **Credit / Debit card**. 4. Enter your credit card information. 5. Click **Upgrade**. The new organization is now set up with credit card billing. You'll use this organization after completing the rest of this process. 3. Migrate your projects to the new Pinecone organization: 1. Go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage) and copy your new organization ID. 2. Go to [**Settings > Support > Tickets**](https://app.pinecone.io/organizations/-/settings/support/ticket/create). 3. For **Ticket category**, select **Project or Organization Management**. 4. For **Subject**, enter "Migrate projects to a new organization". 5. For **Description**, enter the following: ``` I am changing my payment method from Google Cloud Marketplace to credit card. Please migrate my projects to my new organization: `` ``` 6. Click **Submit**. 4. Add your team members to the new organization: 1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members). 2. [Add your team members to the new organization](/guides/organizations/manage-organization-members#add-a-member-to-an-organization). 5. Downgrade your original Pinecone organization: Do not downgrade your original organization until you receive a confirmation that Pinecone has finished the migration to your new organization. 1. In the Pinecone console, go to your original organization. 2. Go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans). 3. In the **Starter** section, click **Downgrade**. 4. Click **Confirm downgrade**. 5. On the **Continue your downgrade on the GCP marketplace** modal, click **Continue to marketplace**. This takes you to your orders page in Google Cloud Marketplace. 6. [Cancel the order](https://cloud.google.com/marketplace/docs/manage-billing#saas-products) for your original organization. If you don't see the order, check that the correct billing account is selected. Going forward, you'll use your new organization and your usage will be billed through the credit card you provided. You can [delete your original organization](/troubleshooting/delete-your-organization). However, before deleting, make sure to [download your past invoices](/guides/organizations/manage-billing/access-your-invoices) since you will lose access to them once the organization is deleted. To change from paying through the AWS Marketplace to paying with a credit card, do the following: 1. Create a new organization in your Pinecone account: 1. In the Pinecone console, go to [**Organizations**](https://app.pinecone.io/organizations/-/settings/account/organizations). 2. Click **+ Create organization**. 3. Enter the name of the new organization and click **Create**. 2. Upgrade the new organization: 1. Go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans). 2. Click **Upgrade** in the **Standard** or **Enterprise** plan section. 3. Click **Credit / Debit card**. 4. Enter your credit card information. 5. Click **Upgrade**. The new organization is now set up with credit card billing. You'll use this organization after completing the rest of this process. 3. Migrate your projects to the new Pinecone organization: 1. Go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage) and copy your new organization ID. 2. Go to [**Settings > Support > Tickets**](https://app.pinecone.io/organizations/-/settings/support/ticket/create). 3. For **Ticket category**, select **Project or Organization Management**. 4. For **Subject**, enter "Migrate projects to a new organization". 5. For **Description**, enter the following: ``` I am changing my payment method from AWS Marketplace to credit card. Please migrate my projects to my new organization: `` ``` 6. Click **Submit**. 4. Add your team members to the new organization: 1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members). 2. [Add your team members to the new organization](/guides/organizations/manage-organization-members#add-a-member-to-an-organization). 5. Downgrade your original Pinecone organization: Do not downgrade your original organization until you receive a confirmation that Pinecone has finished the migration to your new organization. 1. In the Pinecone console, go to your original organization. 2. Go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans). 3. In the **Starter** section, click **Downgrade**. 4. Click **Confirm downgrade**. 5. On the **Continue your downgrade on the AWS marketplace** modal, click **Continue to marketplace**. This takes you to the [Manage subscriptions](https://console.aws.amazon.com/marketplace) page in the AWS Marketplace. 6. [Cancel the subscription](https://docs.aws.amazon.com/marketplace/latest/buyerguide/cancel-subscription.html#cancel-saas-subscription) to Pinecone. Going forward, you'll use your new organization and your usage will be billed through the credit card you provided. You can [delete your original organization](/troubleshooting/delete-your-organization). However, before deleting, make sure to [download your past invoices](/guides/organizations/manage-billing/access-your-invoices) since you will lose access to them once the organization is deleted. To change from paying through the Microsoft Marketplace to paying with a credit card, do the following: 1. Create a new organization in your Pinecone account: 1. In the Pinecone console, go to [**Organizations**](https://app.pinecone.io/organizations/-/settings/account/organizations). 2. Click **+ Create organization**. 3. Enter the name of the new organization and click **Create**. 2. Upgrade the new organization: 1. Go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans). 2. Click **Upgrade** in the **Standard** or **Enterprise** plan section. 3. Click **Credit / Debit card**. 4. Enter your credit card information. 5. Click **Upgrade**. The new organization is now set up with credit card billing. You'll use this organization after completing the rest of this process. 3. Migrate your projects to the new Pinecone organization: 1. Go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage) and copy your new organization ID. 2. Go to [**Settings > Support > Tickets**](https://app.pinecone.io/organizations/-/settings/support/ticket/create). 3. For **Ticket category**, select **Project or Organization Management**. 4. For **Subject**, enter "Migrate projects to a new organization". 5. For **Description**, enter the following: ``` I am changing my payment method from Microsoft Marketplace to credit card. Please migrate my projects to my new organization: `` ``` 6. Click **Submit**. 4. Add your team members to the new organization: 1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members). 2. [Add your team members to the new organization](/guides/organizations/manage-organization-members#add-a-member-to-an-organization). 5. Downgrade your original Pinecone organization: Do not downgrade your original organization until you receive a confirmation that Pinecone has finished the migration to your new organization. 1. In the Pinecone console, go to your original organization. 2. Go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans). 3. In the **Starter** section, click **Downgrade**. 4. Click **Confirm downgrade**. 5. On the **Continue your downgrade on Azure marketplace** modal, click **Continue to marketplace**. 6. On the **SaaS** page, click your subscription to Pinecone. 7. Click **Cancel subscription**. 8. Confirm the cancellation. Going forward, you'll use your new organization and your usage will be billed through the credit card you provided. You can [delete your original organization](/troubleshooting/delete-your-organization). However, before deleting, make sure to [download your past invoices](/guides/organizations/manage-billing/access-your-invoices) since you will lose access to them once the organization is deleted. ## Marketplace → marketplace To change from one marketplace to another, you'll need to: 1. Subscribe to Pinecone in the new marketplace 2. Connect your existing org to the new marketplace 3. Cancel your subscription in the old marketplace To change to a Google Cloud Marketplace billing account, do the following: 1. Subscribe to Pinecone in the Google Cloud Marketplace: 1. In the Google Cloud Marketplace, go to the [Pinecone listing](https://console.cloud.google.com/marketplace/product/pinecone-public/pinecone). 2. Click **Subscribe**. 3. On the **Order Summary** page, select a billing account, accept the terms and conditions, and click **Subscribe**. The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details. 4. On the **Your order request has been sent to Pinecone** modal, click **Sign up with Pinecone**. This takes you to a Google-specific Pinecone login page. 5. Log in to your Pinecone account. Use the same authentication method as your existing Pinecone organization. 2. Connect your existing org to your Google account: 1. On the **Connect GCP to Pinecone** page, select the Pinecone organization that you want to use Google Cloud Marketplace. If you see a message saying that the subscription is still in process, wait a few minutes, refresh the page, and proceed only when the message has disappeared. 2. On the **Confirm GCP marketplace connection** modal, click **Connect**. This takes you to your organization in the Pinecone console. Going forward, your usage of Pinecone will be billed through the Google Cloud Marketplace. 3. Cancel your subscription in your previous marketplace: * For AWS: 1. In the AWS Marketplace, go to the [Manage subscriptions](https://console.aws.amazon.com/marketplace) page in the AWS Marketplace. 2. [Cancel the subscription](https://docs.aws.amazon.com/marketplace/latest/buyerguide/cancel-subscription.html#cancel-saas-subscription) to Pinecone. * For Microsoft: 1. Go to [Azure SaaS Resource Management](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.SaaS%2Fresources). 2. Select your subscription to Pinecone. 3. Click **Cancel subscription**. 4. Confirm the cancellation. To change to an AWS Marketplace billing account, do the following: 1. Subscribe to Pinecone in the AWS Marketplace: 1. In the AWS Marketplace, go to the [Pinecone listing](https://aws.amazon.com/marketplace/pp/prodview-xhgyscinlz4jk) in the AWS Marketplace. 2. Click **View purchase options**. 3. On the **Subscribe to Pinecone Vector Database** page, review the offer and then click **Subscribe**. The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details. 4. You'll see a message stating that your subscription is in process. Click **Set up your account**. This takes you to an AWS-specific Pinecone login page. 5. Log in to your Pinecone account. Use the same authentication method as your existing Pinecone organization. 2. Connect your existing org to your AWS account: 1. On the **Connect AWS to Pinecone** page, select the Pinecone organization that you want to change to AWS Marketplace. If you see a message saying that the subscription is still in process, wait a few minutes, refresh the page, and proceed only when the message has disappeared. 2. On the **Confirm AWS marketplace connection** modal, click **Connect**. This takes you to your organization in the Pinecone console. Going forward, your usage of Pinecone will be billed through the AWS Marketplace. 3. Cancel your subscription in your previous marketplace: * For Google Cloud Marketplace: 1. Go to the [Orders](https://console.cloud.google.com/marketplace/orders) page. 2. [Cancel the order](https://cloud.google.com/marketplace/docs/manage-billing#saas-products) for Pinecone. * For Microsoft Marketplace: 1. Go to [Azure SaaS Resource Management](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.SaaS%2Fresources). 2. Select your subscription to Pinecone. 3. Click **Cancel subscription**. 4. Confirm the cancellation. To change to a Microsoft Marketplace billing account, do the following: 1. Subscribe to Pinecone in the Microsoft Marketplace: 1. In the Microsoft Marketplace, go to the [Pinecone listing](https://marketplace.microsoft.com/product/saas/pineconesystemsinc1688761585469.pineconesaas). 2. Click **Get it now**. 3. Select the **Pinecone - Pay As You Go** plan. 4. Click **Subscribe**. 5. On the **Subscribe to Pinecone** page, select the required details and click **Review + subscribe**. The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details. 6. Click **Subscribe**. 7. After the subscription is approved, click **Configure account now**. This redirects you to an Microsoft-specific Pinecone login page. 8. Log in to your Pinecone account. Use the same authentication method as your existing Pinecone organization. 2. Connect your existing org to your Microsoft account: 1. On the **Connect Azure to Pinecone** page, select the Pinecone organization that you want to change to Microsoft Marketplace. If you see a message saying that the subscription is still in process, wait a few minutes, refresh the page, and proceed only when the message has disappeared. 2. On the **Confirm Azure marketplace connection** modal, click **Connect**. This takes you to your organization in the Pinecone console. Going forward, your usage of Pinecone will be billed through the Microsoft Marketplace. 3. Cancel your subscription in your previous marketplace: * For Google Cloud Marketplace: 1. Go to the [Orders](https://console.cloud.google.com/marketplace/orders) page. 2. [Cancel the order](https://cloud.google.com/marketplace/docs/manage-billing#saas-products) for Pinecone. * For AWS Marketplace: 1. Go to the [Manage subscriptions](https://console.aws.amazon.com/marketplace) page in the AWS Marketplace. 2. [Cancel the subscription](https://docs.aws.amazon.com/marketplace/latest/buyerguide/cancel-subscription.html#cancel-saas-subscription) to Pinecone. ## Credit card → credit card To update your credit card information in the Pinecone console, do the following: 1. Go to [**Settings > Billing > Overview**](https://app.pinecone.io/organizations/-/settings/billing). 2. In the **Billing Contact** section, click **Edit**. 3. Enter your new credit card information. 4. Click **Update**. # Downgrade your plan Source: https://docs.pinecone.io/guides/organizations/manage-billing/downgrade-billing-plan Downgrade your Pinecone organization from a paid plan to the free Starter plan, including plan requirements, index limits, and billing impact. To change your billing plan, you must be an [organization owner or billing admin](/guides/organizations/understanding-organizations#organization-roles). If you are on the Standard plan with credit/debit card billing and want to reduce spend without returning to the free Starter plan, consider [switching to the Builder plan](#switch-from-standard-to-builder) for a flat \$20/month. ## Requirements Before you can downgrade, your organization must be under the [Starter plan quotas](/reference/api/database-limits): * No more than 5 indexes, all serverless and in the `us-east-1` region of AWS * If you have serverless indexes in a region other than `us-east-1`, [create a new serverless index](/guides/index-data/create-an-index#create-a-serverless-index) in `us-east-1`, [re-upsert your data](/guides/index-data/upsert-data) into the new index, and [delete the old index](/guides/manage-data/manage-indexes#delete-an-index). * If you have more than 5 serverless indexes, [delete indexes](/guides/manage-data/manage-indexes#delete-an-index) until you have 5 or fewer. * If you have pod-based indexes, [delete them](/guides/manage-data/manage-indexes#delete-an-index). * No more than 1 project * If you have more than 1 project, [delete all but 1 project](/guides/projects/manage-projects#delete-a-project). * Before you can delete a project, you must [delete all indexes](/guides/manage-data/manage-indexes#delete-an-index) and [delete all collections](/guides/manage-data/back-up-an-index#delete-a-collection) in the project. * No more than 2 GB of data across all of your serverless indexes * If you are storing more than 2 GB of data, [delete records](/guides/manage-data/delete-data) until you're storing less than 2 GB. * No more than 100 namespaces per serverless index * If any serverless index has more than 100 namespaces, [delete namespaces](/guides/manage-data/delete-data#delete-all-records-from-a-namespace) until it has 100 or fewer remaining. * No more than 3 [assistants](/guides/assistant/overview) * If you have more than 3 assistants, [delete assistants](/guides/assistant/manage-assistants#delete-an-assistant) until you have 3 or fewer. * Within the Starter plan's monthly [ingestion](/guides/assistant/pricing-and-limits#ingestion) and token limits * Your usage must fit within the Starter plan limits for [ingestion units](/guides/assistant/pricing-and-limits#ingestion), chat tokens, context tokens, and storage. Reduce files or usage until you are within those limits. * No more than 1 GB of assistant storage * If you have more than 1 GB of assistant storage, [delete files](https://docs.pinecone.io/guides/assistant/manage-files#delete-a-file) until you're storing less than 1 GB. * No more than 2 users * No collections or backups (these are automatically deleted as part of the downgrade process) You do not need to bring [Assistant usage](/guides/assistant/pricing-and-limits) (ingestion, tokens, and so on) under Starter caps before downgrading. If you exceed Starter limits after downgrading, new requests may be blocked until usage is within limits. **Switching from Standard to Builder instead of Starter?** Your organization must be under the [Builder plan quotas](/reference/api/database-limits), backups must be deleted, and any features not available on Builder—such as bulk import, pod-based indexes, storage integrations, RBAC, and SSO—must be removed or stopped. ## Downgrade to the Starter plan The downgrade process is different depending on how you are paying for Pinecone. It is important to start the downgrade process in the Pinecone console, as described below. When you do so, Pinecone checks that you are under the [Starter plan quotas](#requirements) before allowing you to downgrade. In contrast, if you start the downgrade process in one of the cloud marketplaces, Pinecone cannot check that you are under these quotas before allowing you to downgrade. If you are over the quotas, Pinecone will deactivate your account, and you will need to [contact support](https://www.pinecone.io/contact/support/). If you are paying with a credit card, downgrade as follows: 1. In the Pinecone console, go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans). 2. Click **Downgrade** in the **Starter** plan section. Your billing will end immediately. However, you will receive a final invoice for any charges accrued in the current month. If you are paying through the Google Cloud Marketplace, downgrade as follows: 1. In the Pinecone console, go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans). 2. In the **Starter** section, click **Downgrade**. 3. Click **Confirm downgrade**. 4. On the **Continue your downgrade on the GCP marketplace** modal, click **Continue to marketplace**. This takes you to your orders page in Google Cloud Marketplace. 5. [Cancel the order](https://cloud.google.com/marketplace/docs/manage-billing#saas-products) for your Pinecone subscription. If you don't see the order, check that the correct billing account is selected. Your billing will end immediately. However, you will receive a final invoice for any charges accrued in the current month. If you are paying through the AWS Marketplace, downgrade as follows: 1. In the Pinecone console, go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans). 2. In the **Starter** section, click **Downgrade**. 3. Click **Confirm downgrade**. 4. On the **Continue your downgrade on the AWS marketplace** modal, click **Continue to marketplace**. This takes you to the [Manage subscriptions](https://console.aws.amazon.com/marketplace) page in the AWS Marketplace. 5. [Cancel the subscription](https://docs.aws.amazon.com/marketplace/latest/buyerguide/cancel-subscription.html#cancel-saas-subscription) to Pinecone. Your billing will end immediately. However, you will receive a final invoice for any charges accrued in the current month. If you are paying through the Microsoft Marketplace, downgrade as follows: 1. In the Pinecone console, go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans). 2. In the **Starter** section, click **Downgrade**. 3. Click **Confirm downgrade**. 4. On the **Continue your downgrade on Microsoft marketplace** modal, click **Continue to marketplace**. 5. On the **SaaS** page, click your subscription to Pinecone. 6. Click **Cancel subscription**. 7. Confirm the cancellation. Your billing will end immediately. However, you will receive a final invoice for any charges accrued in the current month. ## Switch from Standard to Builder If you are on the **Standard plan** with credit/debit card billing and would like to switch to the [Builder plan](/reference/api/database-limits) (flat \$20/month), do the following: 1. Bring your organization under the [Builder plan quotas](/reference/api/database-limits). In particular, you must be within the Builder plan limits for projects, indexes, namespaces, storage, users, and monthly usage units. 2. In the Pinecone console, go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans). 3. Click **Switch to Builder** in the **Builder** plan section. 4. Confirm the change. After switching, overages are no longer billed—requests that exceed Builder quotas are blocked instead. If you need more capacity, [upgrade back to Standard or Enterprise](/guides/organizations/manage-billing/upgrade-billing-plan) at any time. The [Builder plan](https://www.pinecone.io/pricing/) is available with credit/debit card billing only and is not supported through cloud marketplaces. If you pay through a cloud marketplace, you cannot switch to the Builder plan at this time. [Contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) to be notified when this migration becomes available. # Download a usage report Source: https://docs.pinecone.io/guides/organizations/manage-billing/download-usage-report Download detailed Pinecone usage and cost reports from the console, including index consumption, storage metrics, and per-project spend breakdowns. To view usage and costs across your Pinecone organization, you must be an [organization owner or billing admin](/guides/organizations/understanding-organizations#organization-roles). Also, this feature is available only to organizations on the Standard or Enterprise plans. The **Usage** dashboard in the Pinecone console gives you a detailed report of usage and costs across your organization, broken down by each billable SKU or aggregated by project or service. You can view the report in the console or download it as a CSV file for more detailed analysis. 1. Go to [**Settings > Usage**](https://app.pinecone.io/organizations/-/settings/usage) in the Pinecone console. 2. Select the time range to report on. This defaults to the last 30 days. 3. Select the scope for your report: * **SKU:** The usage and cost for each billable SKU, for example, read units per cloud region, storage size per cloud region, or tokens per embedding model. * **Project:** The aggregated cost for each project in your organization. * **Service:** The aggregated cost for each service your organization uses, for example, database (includes serverless back up and restore), assistants, inference (embedding and reranking), and collections. 4. Choose the specific SKUs, projects, or services you want to report on. This defaults to all. 5. To download the report as a CSV file, click **Download**. The CSV download provides more granular detail than the console view, including breakdowns by individual index as well as project and index tags. Dates are shown in UTC to match billing invoices. Cost data is delayed up to three days from the actual usage date. # Account deactivation for non-payment Source: https://docs.pinecone.io/guides/organizations/manage-billing/non-payment-account-deactivation Learn what happens when a Pinecone account is deactivated for non-payment: 30-day data retention, permanent deletion, and how to reactivate. If your organization has continued non-payment on a paid billing plan, Pinecone may deactivate your account. While your account is deactivated, you cannot use Pinecone services, but your data is retained for a limited time so you can reactivate and recover it. ## Data retention after deactivation When your account is deactivated for non-payment: * Your account data is retained for **30 days** from deactivation. * After 30 days, all account data is **permanently deleted**. This action cannot be undone. This 30-day retention period applies specifically to accounts deactivated for continued non-payment. Other deletion flows, such as when you [delete resources](/guides/production/data-deletion) or [end your relationship with Pinecone](/guides/production/data-deletion), follow different retention timelines described in the [data deletion policy](/guides/production/data-deletion). If you see a deactivation notice in the Pinecone console, it reflects this policy: > Your account has been deactivated due to continued non-payment. Account data will be retained for 30 days. After 30 days, all data will be permanently deleted. This action cannot be undone. > > To reactivate your account and preserve your data, please visit the billing page and update your payment information. If you believe this is an error, please reach out to our support team. ## Reactivate your account To reactivate your account and preserve your data before the 30-day retention period ends: 1. Sign in to the [Pinecone console](https://app.pinecone.io). 2. Go to [**Settings > Billing**](https://app.pinecone.io/organizations/-/settings/billing). 3. Update your payment information or resolve the outstanding balance. Organization [owners and billing admins](/guides/organizations/understanding-organizations#organization-roles) can update billing details. For help changing how you pay, see [Change your payment method](/guides/organizations/manage-billing/change-payment-method). ## API access while deactivated API requests may fail with a [**402 - Payment Required**](/reference/api/errors#402---payment-required) response while your account has a payment issue or is deactivated for non-payment. After you reactivate your account, retry your requests. For general error-handling guidance, see [Error handling](/guides/production/error-handling). ## Contact support If you believe your account was deactivated in error, [contact Support](https://www.pinecone.io/contact/support/) or [open a support ticket](https://app.pinecone.io/organizations/-/settings/support/ticket) from the console. ## See also * [Change your payment method](/guides/organizations/manage-billing/change-payment-method) * [Data deletion on Pinecone](/guides/production/data-deletion) * [Billing disputes and refunds](/troubleshooting/billing-disputes-and-refunds) # Standard trial Source: https://docs.pinecone.io/guides/organizations/manage-billing/standard-trial Get $300 in credits over 21 days with the Pinecone Standard plan trial, including RBAC, bulk import, backup and restore, and higher scale limits. The Standard trial lets you evaluate Pinecone without requiring any up-front payment. You get \$300 in credits over 21 days with access to Standard plan [features](https://www.pinecone.io/pricing/) and [limits](/reference/api/database-limits) that are suitable for testing Pinecone at scale. If you're building a small or personal project, consider the free [Starter plan](https://www.pinecone.io/pricing/) or the flat-rate [Builder plan](https://www.pinecone.io/pricing/) instead. ## Key features * \$300 in credits * 21 days of access to Standard plan [features](https://www.pinecone.io/pricing/), including: * [Bulk import](/guides/index-data/import-data) * [Backup and restore](/guides/manage-data/backups-overview) * [RBAC (role-based access control)](/guides/production/security-overview#role-based-access-controls-rbac) * [Higher limits](/reference/api/database-limits) for testing at scale * Access to all [cloud regions](/guides/index-data/create-an-index#cloud-regions) * Access to [Developer Support](https://www.pinecone.io/pricing/?plans=support) ## Expiration At the end of a Standard trial, or when you've used all of your credits, you can take one of the following actions: * Add a payment method and continue on with the Standard plan. * Upgrade to the Enterprise plan. * [Downgrade to the Starter plan](#downgrading-to-the-starter-plan) (you can also do this before your trial expires, if you choose). Learn more about [pricing](https://www.pinecone.io/pricing/). ## Downgrading to the Starter plan To downgrade from a Standard trial to the Starter plan, you'll need to bring your usage within Starter plan limits. * No more than 5 indexes, all serverless and in the `us-east-1` region of AWS * If you have serverless indexes in a region other than `us-east-1`, [create a new serverless index](/guides/index-data/create-an-index#create-a-serverless-index) in `us-east-1`, [re-upsert your data](/guides/index-data/upsert-data) into the new index, and [delete the old index](/guides/manage-data/manage-indexes#delete-an-index). * If you have more than 5 serverless indexes, [delete indexes](/guides/manage-data/manage-indexes#delete-an-index) until you have 5 or fewer. * If you have pod-based indexes, [delete them](/guides/manage-data/manage-indexes#delete-an-index). * No more than 1 project * If you have more than 1 project, [delete all but 1 project](/guides/projects/manage-projects#delete-a-project). * Before you can delete a project, you must [delete all indexes](/guides/manage-data/manage-indexes#delete-an-index) and [delete all collections](/guides/manage-data/back-up-an-index#delete-a-collection) in the project. * No more than 2 GB of data across all of your serverless indexes * If you are storing more than 2 GB of data, [delete records](/guides/manage-data/delete-data) until you're storing less than 2 GB. * No more than 100 namespaces per serverless index * If any serverless index has more than 100 namespaces, [delete namespaces](/guides/manage-data/delete-data#delete-all-records-from-a-namespace) until it has 100 or fewer remaining. * No more than 3 [assistants](/guides/assistant/overview) * If you have more than 3 assistants, [delete assistants](/guides/assistant/manage-assistants#delete-an-assistant) until you have 3 or fewer. * Within the Starter plan's monthly [ingestion](/guides/assistant/pricing-and-limits#ingestion) and token limits * Your usage must fit within the Starter plan limits for [ingestion units](/guides/assistant/pricing-and-limits#ingestion), chat tokens, context tokens, and storage. Reduce files or usage until you are within those limits. * No more than 1 GB of assistant storage * If you have more than 1 GB of assistant storage, [delete files](https://docs.pinecone.io/guides/assistant/manage-files#delete-a-file) until you're storing less than 1 GB. * No more than 2 users * No collections or backups (these are automatically deleted as part of the downgrade process) You do not need to bring [Assistant usage](/guides/assistant/pricing-and-limits) (ingestion, tokens, and so on) under Starter caps before downgrading. If you exceed Starter limits after downgrading, new requests may be blocked until usage is within limits. **Switching from Standard to Builder instead of Starter?** Your organization must be under the [Builder plan quotas](/reference/api/database-limits), backups must be deleted, and any features not available on Builder—such as bulk import, pod-based indexes, storage integrations, RBAC, and SSO—must be removed or stopped. If you have questions, [contact Support](https://www.pinecone.io/contact/support/). ## Limits * Each organization is allowed only one trial. * Organizations already on a Builder, Standard, or Enterprise plan cannot activate a Standard plan trial. * Organizations that initially subscribed to Pinecone through marketplace partners cannot activate a Standard plan trial. If you have any questions, [contact Support](https://www.pinecone.io/contact/support/). # Upgrade your plan Source: https://docs.pinecone.io/guides/organizations/manage-billing/upgrade-billing-plan Upgrade to a paid Pinecone plan for higher limits, backups, private endpoints, audit logs, and access to the Builder, Standard, or Enterprise tiers. This page describes how to upgrade from the free Starter plan to the [Builder, Standard, or Enterprise plan](https://www.pinecone.io/pricing/), paying either with a credit/debit card or through a supported cloud marketplace. To change your plan, you must be an [organization owner or billing admin](/guides/organizations/understanding-organizations#organization-roles). To commit to annual spending, [contact Pinecone](https://www.pinecone.io/contact). ## Upgrade to the Builder plan The Builder plan is a flat \$20/month plan with higher quotas than Starter and no usage overages. To upgrade from Starter to Builder: 1. In the Pinecone console, go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans). 2. Click **Upgrade** in the **Builder** plan section. 3. Enter your credit/debit card information. 4. Click **Upgrade**. After upgrading, your organization is immediately on the Builder plan with the higher [Builder plan quotas](/reference/api/database-limits). If you need additional capacity or features not included in Builder, you can [upgrade to Standard or Enterprise](#upgrade-to-the-standard-or-enterprise-plan) at any time. The [Builder plan](https://www.pinecone.io/pricing/) is available with credit/debit card billing only and is not supported through cloud marketplaces. ## Upgrade to the Standard or Enterprise plan ### Pay with a credit/debit card To upgrade your plan to Standard or Enterprise and pay with a credit/debit card, do the following: 1. In the Pinecone console, go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans). 2. Click **Upgrade** in the **Standard** or **Enterprise** plan section. 3. Click **Credit / Debit card**. 4. Enter your credit card information. 5. Click **Upgrade**. After upgrading, you will immediately start paying for usage of your Pinecone indexes, including the serverless indexes that were free on the Starter plan. For more details about how costs are calculated, see [Understanding cost](/guides/manage-cost/understanding-cost). ### Pay through the Google Cloud Marketplace To upgrade your plan to Standard or Enterprise and pay through the Google Cloud Marketplace, do the following: 1. In the Pinecone console, go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans). 2. Click **Upgrade** in the **Standard** or **Enterprise** plan section. 3. Click **Billing through GCP**. This takes you to the [Pinecone listing](https://console.cloud.google.com/marketplace/product/pinecone-public/pinecone) in the Google Cloud Marketplace. 4. Click **Subscribe**. 5. On the **Order Summary** page, select a billing account, accept the terms and conditions, and click **Subscribe**. The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details. 6. On the **Your order request has been sent to Pinecone** modal, click **Sign up with Pinecone**. This takes you to a Google-specific Pinecone login page. 7. Log in to your Pinecone account. Use the same authentication method as your existing Pinecone organization. 8. Select an organization from the list. You can only connect to organizations that are on the [Starter plan](https://www.pinecone.io/pricing/). Alternatively, you can opt to create a new organization. 9. Click **Connect to Pinecone** and follow the prompts. Once your organization is connected and upgraded, you will receive a confirmation message. You will then immediately start paying for usage of your Pinecone indexes, including the serverless indexes that were free on the Starter plan. For more details about how costs are calculated, see [Understanding cost](/guides/manage-cost/understanding-cost). ### Pay through the AWS Marketplace To upgrade your plan to Standard or Enterprise and pay through the AWS Marketplace, do the following: 1. In the Pinecone console, go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans). 2. Click **Upgrade** in the **Standard** or **Enterprise** plan section. 3. Click **Billing through AWS**. This takes you to the [Pinecone listing](https://aws.amazon.com/marketplace/pp/prodview-xhgyscinlz4jk) in the AWS Marketplace. 4. Click **View purchase options**. 5. On the **Subscribe to Pinecone Vector Database** page, review the offer and then click **Subscribe**. The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details. 6. You'll see a message stating that your subscription is in process. Click **Set up your account**. This takes you to an AWS-specific Pinecone login page. If the [Pinecone subscription page](https://aws.amazon.com/marketplace/saas/ordering?productId=738798c3-eeca-494a-a2a9-161bee9450b2) shows a message stating, “You are currently subscribed to this offer,” contact your team members to request an invitation to the existing AWS-linked organization. The **Set up your account** button is clickable, but Pinecone does not create a new AWS-linked organization. 7. Log in to your Pinecone account. Use the same authentication method as your existing Pinecone organization. 8. Select an organization from the list. You can only connect to organizations that are on the [Starter plan](https://www.pinecone.io/pricing/). Alternatively, you can opt to create a new organization. 9. Click **Connect to Pinecone** and follow the prompts. Once your organization is connected and upgraded, you will receive a confirmation message. You will then immediately start paying for usage of your Pinecone indexes, including the serverless indexes that were free on the Starter plan. For more details about how costs are calculated, see [Understanding cost](/guides/manage-cost/understanding-cost). ### Pay through the Microsoft Marketplace To upgrade your plan to Standard or Enterprise and pay through the Microsoft Marketplace, do the following: 1. In the Pinecone console, go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans). 2. Click **Upgrade** in the **Standard** or **Enterprise** plan section. 3. Click **Billing through Azure**. This takes you to the [Pinecone listing](https://marketplace.microsoft.com/product/saas/pineconesystemsinc1688761585469.pineconesaas) in the Microsoft Marketplace. 4. Click **Get it now**. 5. Select the **Pinecone - Pay As You Go** plan. 6. Click **Subscribe**. 7. On the **Subscribe to Pinecone** page, select the required details and click **Review + subscribe**. The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details. 8. Click **Subscribe**. 9. After the subscription is approved, click **Configure account now**. This redirects you to an Microsoft-specific Pinecone login page. 10. Log in to your Pinecone account. Use the same authentication method as your existing Pinecone organization. 11. Select an organization from the list. You can only connect to organizations that are on the [Starter plan](https://www.pinecone.io/pricing/). Alternatively, you can opt to create a new organization. 12. Click **Connect to Pinecone** and follow the prompts. Once your organization is connected and upgraded, you will receive a confirmation message. You will then immediately start paying for usage of your Pinecone indexes, including the serverless indexes that were free on the Starter plan. For more details about how costs are calculated, see [Understanding cost](/guides/manage-cost/understanding-cost). # Manage organization members Source: https://docs.pinecone.io/guides/organizations/manage-organization-members Add, invite, and manage members in your Pinecone organization, including assigning organization roles, changing permissions, and removing users. This page shows how [organization owners](/guides/organizations/understanding-organizations#organization-roles) can add and manage organization members. To assign and manage roles programmatically with the Admin API, or to manage roles for service accounts and API keys, see [Manage roles and access](/guides/production/manage-rbac). For information about managing members at the **project-level**, see [Manage project members](/guides/projects/manage-project-members). ## Add a member to an organization You can add members to your organization in the [Pinecone console](https://app.pinecone.io): 1. Go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members). 2. In the **Invite by email** field, enter the member's email address. 3. Choose an [**Organization role**](/guides/organizations/understanding-organizations#organization-roles) for the member. The role determines the member's permissions within Pinecone. 4. Click **Invite**. When you invite a member to join your organization, Pinecone sends them an email containing a link that enables them to gain access to the organization or project. If they already have a Pinecone account, they still receive an email, but they can also immediately view the project. ## Change a member's role You can change a member's role in the [Pinecone console](https://app.pinecone.io): 1. Go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members). 2. In the row of the member whose role you want to change, click **ellipsis (...) menu > Edit role**. 3. Select an [**Organization role**](/guides/organizations/understanding-organizations#organization-roles) for the member. 4. Click **Edit role**. ## Remove a member You can remove a member from your organization in the [Pinecone console](https://app.pinecone.io): 1. Go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members). 2. In the row of the member you want to remove, click **ellipsis (...) menu > Remove member**. 3. Click **Remove Member**. To remove yourself from an organization, click the **Leave organization** button in your user's row and confirm. # Manage service accounts at the organization-level Source: https://docs.pinecone.io/guides/organizations/manage-service-accounts Create and manage service accounts at the organization level in Pinecone for programmatic Admin API access, including client secrets and role assignment. This feature is in [public preview](/release-notes/feature-availability) and available only on [Enterprise plans](https://www.pinecone.io/pricing/). This page shows how [organization owners](/guides/organizations/understanding-organizations#organization-roles) can add and manage service accounts at the organization-level. Service accounts enable programmatic access to Pinecone's Admin API, which can be used to create and manage projects and API keys. Once a service account is added at the organization-level, it can be added to a project. For more information, see [Manage service accounts at the project-level](/guides/projects/manage-service-accounts). ## Create a service account You can create a service account in the [Pinecone console](https://app.pinecone.io): 1. Go to [**Settings > Access > Service accounts**](https://app.pinecone.io/organizations/-/settings/access/service-accounts). 2. Enter a **Name** for the service account. 3. Choose an [**Organization role**](/guides/organizations/understanding-organizations#organization-roles) for the service account. The role determines the service account's permissions within Pinecone. 4. Click **Create**. 5. Copy and save the **Client secret** in a secure place for future use. You will need the client secret to retrieve an access token. You will not be able to see the client secret again after you close the dialog. 6. Click **Close**. Once you have created a service account, [add it to a project](/guides/projects/manage-service-accounts#add-a-service-account-to-a-project) to allow it access to the project's resources. ## Retrieve an access token To access the Admin API, you must provide an access token to authenticate. Retrieve the access token using the client secret of a service account, which was [provided at time of creation](#create-a-service-account). You can retrieve an access token for a service account from the `https://login.pinecone.io/oauth/token` endpoint, as shown in the following example: ```bash curl theme={null} curl "https://login.pinecone.io/oauth/token" \ # Note: Base URL is login.pinecone.io -H "X-Pinecone-Api-Version: 2025-10" \ -H "Content-Type: application/json" \ -d '{ "grant_type": "client_credentials", "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "audience": "https://api.pinecone.io/" }' ``` The response will include an `access_token` field, which you can use to authenticate with the Admin API. ``` { "access_token":"YOUR_ACCESS_TOKEN", "expires_in":86400, "token_type":"Bearer" } ``` ## Change a service account's role You can change a service account's role in the [Pinecone console](https://app.pinecone.io): 1. Go to [**Settings > Access > Service accounts**](https://app.pinecone.io/organizations/-/settings/access/service-accounts). 2. In the row of the service account you want to update, click **ellipsis (...) menu > Manage**. 3. Select an [**Organization role**](/guides/organizations/understanding-organizations#organization-roles) for the service account. 4. Click **Update**. ## Update service account name You can change a service account's name in the [Pinecone console](https://app.pinecone.io): 1. Go to [**Settings > Access > Service accounts**](https://app.pinecone.io/organizations/-/settings/access/service-accounts). 2. In the row of the service account you want to update, click **ellipsis (...) menu > Manage**. 3. Enter a new **Service account name**. 4. Click **Update**. ## Rotate a service account's secret You can rotate a service account's client secret in the [Pinecone console](https://app.pinecone.io): 1. Go to [**Settings > Access > Service accounts**](https://app.pinecone.io/organizations/-/settings/access/service-accounts). 2. In the row of the service account you want to update, click **ellipsis (...) menu > Rotate secret**. 3. **Enter the service account name** to confirm. 4. Click **Rotate client secret**. 5. Copy and save the **Client secret** in a secure place for future use. You will not be able to see the client secret again after you close the dialog. 6. Click **Close**. ## Delete a service account Deleting a service account will remove it from all projects and will disrupt any applications using it to access Pinecone. You delete a service account in the [Pinecone console](https://app.pinecone.io): 1. Go to [**Settings > Access > Service accounts**](https://app.pinecone.io/organizations/-/settings/access/service-accounts). 2. In the row of the service account you want to update, click **ellipsis (...) menu > Delete**. 3. **Enter the service account name** to confirm. 4. Click **Delete service account**. # Understanding organizations Source: https://docs.pinecone.io/guides/organizations/understanding-organizations Learn how Pinecone organizations group projects, share billing, and use organization roles to control member permissions and access to resources. A Pinecone organization is a set of [projects](/guides/projects/understanding-projects) that use the same billing. Organizations allow one or more users to control billing and project permissions for all of the projects belonging to the organization. Each project belongs to an organization. While an email address can be associated with multiple organizations, it cannot be used to create more than one organization. For information about managing organization members, see [Manage organization members](/guides/organizations/manage-organization-members). ## Projects in an organization Each organization contains one or more projects that share the same organization owners and billing settings. Each project belongs to exactly one organization. If you need to move a project from one organization to another, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ## Billing settings All of the projects in an organization share the same billing method and settings. The billing settings for the organization are controlled by the organization owners. Organization owners can update the billing contact information, update the payment method, and view and download invoices using the [Pinecone console](https://app.pinecone.io/organizations/-/settings/billing). ## Organization roles Organization owners can manage access to their organizations and projects by assigning roles to organization members and service accounts. A role determines the permissions that a [principal](/guides/production/security-overview#role-based-access-controls-rbac) (a user, service account, or API key) has within Pinecone. The organization roles are as follows: * **Organization owner** (`OrgOwner`): Full control over the organization, including billing, members, service accounts, security, and every project. Inherits [owner access](/guides/projects/understanding-projects#project-roles) to all projects in the organization. * **Organization manager** (`OrgManager`): Can view organization details and create projects. Organization managers cannot manage billing, members, service accounts, or organization settings. * **Organization member** (`OrgMember`): Can view organization details and access the projects they are added to. Organization members cannot create projects or manage organization settings. To grant project access, add the member to one or more projects and assign a [project role](/guides/projects/understanding-projects#project-roles); see [Manage project members](/guides/projects/manage-project-members). * **Billing admin** (`OrgBillingAdmin`): Can view organization details and manage billing, subscriptions, and usage. Billing admins cannot manage members or organization settings, and they cannot manage projects unless they are also [project owners](/guides/projects/understanding-projects#project-roles). The following table summarizes the permissions for each organization role: | Permission | Owner | Manager | Member | Billing admin | | -------------------------------------- | :---: | :-----: | :----: | :-----------: | | View account details | ✓ | ✓ | ✓ | ✓ | | Create projects | ✓ | ✓ | | | | View billing and usage details | ✓ | | | ✓ | | Manage billing details | ✓ | | | ✓ | | Invite and remove organization members | ✓ | | | | | Update organization member roles | ✓ | | | | | Manage service accounts | ✓ | | | | | Configure single sign-on (SSO) | ✓ | | | | | Configure audit logs | ✓ | | | | | Update organization name | ✓ | | | | | Delete the organization | ✓ | | | | ## Organization single sign-on (SSO) SSO allows organizations to manage their teams' access to Pinecone through their identity management solution. Once your integration is configured, you can specify a default role for teammates when they sign up. For organizations that use SSO for authentication, console sessions are re-authenticated at least every 24 hours. For more information, see [Configure single sign-on](/guides/production/configure-single-sign-on/okta). SSO is available on Standard and Enterprise plans. ## Service accounts This feature is in [public preview](/release-notes/feature-availability) and available only on [Enterprise plans](https://www.pinecone.io/pricing/). [Service accounts](/guides/organizations/manage-service-accounts) enable programmatic access to Pinecone's Admin API, which can be used to create and manage projects and API keys. Use service accounts to automate infrastructure management and integrate Pinecone into your deployment workflows, rather than through manual actions in the Pinecone console. Service accounts use the [organization roles](/guides/organizations/understanding-organizations#organization-roles) and [project role](/guides/projects/understanding-projects#project-roles) for permissioning, and provide a secure and auditable way to handle programmatic access. ## See also * [Manage organization members](/guides/organizations/manage-organization-members) * [Manage project members](/guides/projects/manage-project-members) # CI/CD with Pinecone Local and GitHub Actions Source: https://docs.pinecone.io/guides/production/automated-testing Build a GitHub Actions CI/CD workflow with Pinecone Local to run automated integration tests against an in-memory emulator without touching production. Pinecone Local is an in-memory Pinecone Database emulator available as a Docker image. This page shows you how to build a CI/CD workflow with Pinecone Local and [GitHub Actions](https://docs.github.com/en/actions) to test your integration without connecting to your Pinecone account, affecting production data, or incurring any usage or storage fees. Pinecone Local is not suitable for production. See [Limitations](#limitations) for details. ## Limitations Pinecone Local has the following limitations: * Pinecone Local uses the `2025-01` API version, which is not the latest stable version. * Pinecone Local is available in Docker only. * Pinecone Local is an in-memory emulator and is not suitable for production. Records loaded into Pinecone Local do not persist after it is stopped. * Pinecone Local does not authenticate client requests. API keys are ignored. * Max number of records per index: 100,000. Pinecone Local does not currently support the following features: * [Import from object storage](/guides/index-data/import-data) * [Backup/restore of serverless indexes](/guides/manage-data/backups-overview) * [Collections for pod-based indexes](/guides/indexes/pods/understanding-collections) * [Namespace management](/guides/manage-data/manage-namespaces) * [Pinecone Inference](/reference/api/introduction#inference) * [Pinecone Assistant](/guides/assistant/overview) ## 1. Write your tests Running code against Pinecone Local is just like running code against your Pinecone account, with the following differences: * Pinecone Local does not authenticate client requests. API keys are ignored. * The latest version of Pinecone Local uses [Pinecone API version](/reference/api/versioning) `2025-01` and requires [Python SDK](/reference/sdks/python/overview) `v6.x` or later, [Node.js SDK](/reference/sdks/node/overview) `v5.x` or later, [Java SDK](/reference/sdks/java/overview) `v4.x` or later, and [Go SDK](/reference/sdks/go/overview) `v3.x` or later. Be sure to review the [limitations](#limitations) of Pinecone Local before using it for development or testing. **Example** The following example assumes that you have [started Pinecone Local without indexes](/guides/operations/local-development#database-emulator). It initializes a client, creates [an index for dense vectors](/guides/index-data/indexing-overview#indexes-with-dense-vectors) and [an index for sparse vectors](/guides/index-data/indexing-overview#indexes-with-sparse-vectors), upserts records into each, checks their record counts, and queries them. ```python Python theme={null} from pinecone.grpc import PineconeGRPC, GRPCClientConfig from pinecone import ServerlessSpec # Initialize a client. # API key is required, but the value does not matter. # Host and port of the Pinecone Local instance # is required when starting without indexes. pc = PineconeGRPC( api_key="pclocal", host="http://localhost:5080" ) # Create two indexes, one dense and one sparse dense_index_name = "dense-index" sparse_index_name = "sparse-index" if not pc.has_index(dense_index_name): dense_index_model = pc.create_index( name=dense_index_name, vector_type="dense", dimension=2, metric="cosine", spec=ServerlessSpec(cloud="aws", region="us-east-1"), deletion_protection="disabled", tags={"environment": "development"} ) print("Index model (dense):\n", dense_index_model) if not pc.has_index(sparse_index_name): sparse_index_model = pc.create_index( name=sparse_index_name, vector_type="sparse", metric="dotproduct", spec=ServerlessSpec(cloud="aws", region="us-east-1"), deletion_protection="disabled", tags={"environment": "development"} ) print("\nIndex model (sparse):\n", sparse_index_model) # Target each index, disabling tls dense_index_host = pc.describe_index(name=dense_index_name).host dense_index = pc.Index(host=dense_index_host, grpc_config=GRPCClientConfig(secure=False)) sparse_index_host = pc.describe_index(name=sparse_index_name).host sparse_index = pc.Index(host=sparse_index_host, grpc_config=GRPCClientConfig(secure=False)) # Upsert records into the index (dense) dense_index.upsert( vectors=[ { "id": "vec1", "values": [1.0, -2.5], "metadata": {"genre": "drama"} }, { "id": "vec2", "values": [3.0, -2.0], "metadata": {"genre": "documentary"} }, { "id": "vec3", "values": [0.5, -1.5], "metadata": {"genre": "documentary"} } ], namespace="example-namespace" ) # Upsert records into the index (sparse) sparse_index.upsert( namespace="example-namespace", vectors=[ { "id": "vec1", "sparse_values": { "values": [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688], "indices": [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191] }, "metadata": { "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "category": "technology", "quarter": "Q3" } }, { "id": "vec2", "sparse_values": { "values": [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469], "indices": [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697] }, "metadata": { "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4" } }, { "id": "vec3", "sparse_values": { "values": [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094], "indices": [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697] }, "metadata": { "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", "category": "technology", "quarter": "Q3" } } ] ) # Check the number of records in each index print("\nIndex stats (dense):\n", dense_index.describe_index_stats()) print("\nIndex stats (sparse):\n", sparse_index.describe_index_stats()) # Query the index (dense) with a metadata filter dense_response = dense_index.query( namespace="example-namespace", vector=[3.0, -2.0], filter={"genre": {"$eq": "documentary"}}, top_k=1, include_values=False, include_metadata=True ) print("\nDense query response:\n", dense_response) # Query the index (sparse) with a metadata filter sparse_response = sparse_index.query( namespace="example-namespace", sparse_vector={ "values": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0], "indices": [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697] }, filter={ "quarter": {"$eq": "Q4"} }, top_k=1, include_values=False, include_metadata=True ) print("/nSparse query response:\n", sparse_response) # Delete the indexes pc.delete_index(name=dense_index_name) pc.delete_index(name=sparse_index_name) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; // Initialize a client. // API key is required, but the value does not matter. // Host and port of the Pinecone Local instance // is required when starting without indexes. const pc = new Pinecone({ apiKey: 'pclocal', controllerHostUrl: 'http://localhost:5080' }); // Create two indexes, one dense and one sparse const denseIndexName = 'dense-index'; const sparseIndexName = 'sparse-index'; const denseIndexModel = await pc.createIndex({ name: denseIndexName, vectorType: 'dense', dimension: 2, metric: 'cosine', spec: { serverless: { cloud: 'aws', region: 'us-east-1' } }, deletionProtection: 'disabled', tags: { environment: 'development' }, }); console.log('Index model (dense):', denseIndexModel); const sparseIndexModel = await pc.createIndex({ name: sparseIndexName, vectorType: 'sparse', metric: 'dotproduct', spec: { serverless: { cloud: 'aws', region: 'us-east-1' } }, deletionProtection: 'disabled', tags: { environment: 'development' }, }); console.log('\nIndex model (sparse):', sparseIndexModel); // Target each index const denseIndexHost = (await pc.describeIndex(denseIndexName)).host; const denseIndex = await pc.index(denseIndexName, 'http://' + denseIndexHost); const sparseIndexHost = (await pc.describeIndex(sparseIndexName)).host; const sparseIndex = await pc.index(sparseIndexName, 'http://' + sparseIndexHost); // Upsert records into the index (dense) await denseIndex.namespace('example-namespace').upsert([ { id: 'vec1', values: [1.0, -2.5], metadata: { genre: 'drama' }, }, { id: 'vec2', values: [3.0, -2.0], metadata: { genre: 'documentary' }, }, { id: 'vec3', values: [0.5, -1.5], metadata: { genre: 'documentary' }, } ]); // Upsert records into the index (sparse) await sparseIndex.namespace('example-namespace').upsert([ { id: 'vec1', sparseValues: { indices: [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191], values: [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688] }, metadata: { chunk_text: 'AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.', category: 'technology', quarter: 'Q3' } }, { id: 'vec2', sparseValues: { indices: [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697], values: [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469] }, metadata: { chunk_text: "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.", category: 'technology', quarter: 'Q4' } }, { id: 'vec3', sparseValues: { indices: [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697], values: [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094] }, metadata: { chunk_text: "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", category: 'technology', quarter: 'Q3' } } ]); // Check the number of records in each index console.log('\nIndex stats (dense):', await denseIndex.describeIndexStats()); console.log('\nIndex stats (sparse):', await sparseIndex.describeIndexStats()); // Query the index (dense) with a metadata filter const denseQueryResponse = await denseIndex.namespace('example-namespace').query({ vector: [3.0, -2.0], filter: { 'genre': {'$eq': 'documentary'} }, topK: 1, includeValues: false, includeMetadata: true, }); console.log('\nDense query response:', denseQueryResponse); const sparseQueryResponse = await sparseIndex.namespace('example-namespace').query({ sparseVector: { indices: [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697], values: [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0] }, topK: 1, includeValues: false, includeMetadata: true }); console.log('\nSparse query response:', sparseQueryResponse); // Delete the index await pc.deleteIndex(denseIndexName); await pc.deleteIndex(sparseIndexName); ``` ```java Java theme={null} import com.google.protobuf.Struct; import com.google.protobuf.Value; import io.pinecone.clients.Index; import io.pinecone.clients.Pinecone; import io.pinecone.proto.DescribeIndexStatsResponse; import org.openapitools.db_control.client.model.DeletionProtection; import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices; import java.util.*; public class PineconeLocalExample { public static void main(String[] args) { // Initialize a client. // API key is required, but the value does not matter. // When starting without indexes, disable TLS and // provide the host and port of the Pinecone Local instance. String host = "http://localhost:5080"; Pinecone pc = new Pinecone.Builder("pclocal") .withHost(host) .withTlsEnabled(false) .build(); // Create two indexes, one dense and one sparse String denseIndexName = "dense-index"; String sparseIndexName = "sparse-index"; HashMap tags = new HashMap<>(); tags.put("environment", "development"); pc.createServerlessIndex( denseIndexName, "cosine", 2, "aws", "us-east-1", DeletionProtection.DISABLED, tags ); pc.createSparseServelessIndex( sparseIndexName, "aws", "us-east-1", DeletionProtection.DISABLED, tags, "sparse" ); // Get index connection objects Index denseIndexConnection = pc.getIndexConnection(denseIndexName); Index sparseIndexConnection = pc.getIndexConnection(sparseIndexName); // Upsert records into the index (dense) Struct metaData1 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("drama").build()) .build(); Struct metaData2 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("documentary").build()) .build(); Struct metaData3 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("documentary").build()) .build(); denseIndexConnection.upsert("vec1", Arrays.asList(1.0f, -2.5f), null, null, metaData1, "example-namespace"); denseIndexConnection.upsert("vec2", Arrays.asList(3.0f, -2.0f), null, null, metaData2, "example-namespace"); denseIndexConnection.upsert("vec3", Arrays.asList(0.5f, -1.5f), null, null, metaData3, "example-namespace"); // Upsert records into the index (sparse) ArrayList indices1 = new ArrayList<>(Arrays.asList( 822745112L, 1009084850L, 1221765879L, 1408993854L, 1504846510L, 1596856843L, 1640781426L, 1656251611L, 1807131503L, 2543655733L, 2902766088L, 2909307736L, 3246437992L, 3517203014L, 3590924191L )); ArrayList values1 = new ArrayList<>(Arrays.asList( 1.7958984f, 0.41577148f, 2.828125f, 2.8027344f, 2.8691406f, 1.6533203f, 5.3671875f, 1.3046875f, 0.49780273f, 0.5722656f, 2.71875f, 3.0820312f, 2.5019531f, 4.4414062f, 3.3554688f )); Struct sparseMetaData1 = Struct.newBuilder() .putFields("chunk_text", Value.newBuilder().setStringValue("AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.").build()) .putFields("category", Value.newBuilder().setStringValue("technology").build()) .putFields("quarter", Value.newBuilder().setStringValue("Q3").build()) .build(); ArrayList indices2 = new ArrayList<>(Arrays.asList( 131900689L, 592326839L, 710158994L, 838729363L, 1304885087L, 1640781426L, 1690623792L, 1807131503L, 2066971792L, 2428553208L, 2548600401L, 2577534050L, 3162218338L, 3319279674L, 3343062801L, 3476647774L, 3485013322L, 3517203014L, 4283091697L )); ArrayList values2 = new ArrayList<>(Arrays.asList( 0.4362793f, 3.3457031f, 2.7714844f, 3.0273438f, 3.3164062f, 5.6015625f, 2.4863281f, 0.38134766f, 1.25f, 2.9609375f, 0.34179688f, 1.4306641f, 0.34375f, 3.3613281f, 1.4404297f, 2.2558594f, 2.2597656f, 4.8710938f, 0.5605469f )); Struct sparseMetaData2 = Struct.newBuilder() .putFields("chunk_text", Value.newBuilder().setStringValue("Analysts suggest that AAPL'\\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.").build()) .putFields("category", Value.newBuilder().setStringValue("technology").build()) .putFields("quarter", Value.newBuilder().setStringValue("Q4").build()) .build(); ArrayList indices3 = new ArrayList<>(Arrays.asList( 8661920L, 350356213L, 391213188L, 554637446L, 1024951234L, 1640781426L, 1780689102L, 1799010313L, 2194093370L, 2632344667L, 2641553256L, 2779594451L, 3517203014L, 3543799498L, 3837503950L, 4283091697L )); ArrayList values3 = new ArrayList<>(Arrays.asList( 2.6875f, 4.2929688f, 3.609375f, 3.0722656f, 2.1152344f, 5.78125f, 3.7460938f, 3.7363281f, 1.2695312f, 3.4824219f, 0.7207031f, 0.0826416f, 4.671875f, 3.7011719f, 2.796875f, 0.61621094f )); Struct sparseMetaData3 = Struct.newBuilder() .putFields("chunk_text", Value.newBuilder().setStringValue("AAPL'\\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production").build()) .putFields("category", Value.newBuilder().setStringValue("technology").build()) .putFields("quarter", Value.newBuilder().setStringValue("Q3").build()) .build(); sparseIndexConnection.upsert("vec1", Collections.emptyList(), indices1, values1, sparseMetaData1, "example-namespace"); sparseIndexConnection.upsert("vec2", Collections.emptyList(), indices2, values2, sparseMetaData2, "example-namespace"); sparseIndexConnection.upsert("vec3", Collections.emptyList(), indices3, values3, sparseMetaData3, "example-namespace"); // Check the number of records each the index DescribeIndexStatsResponse denseIndexStatsResponse = denseIndexConnection.describeIndexStats(null); System.out.println("Index stats (dense):"); System.out.println(denseIndexStatsResponse); DescribeIndexStatsResponse sparseIndexStatsResponse = sparseIndexConnection.describeIndexStats(null); System.out.println("Index stats (sparse):"); System.out.println(sparseIndexStatsResponse); // Query the index (dense) with a metadata filter List queryVector = Arrays.asList(1.0f, 1.5f); QueryResponseWithUnsignedIndices denseQueryResponse = denseIndexConnection.query(1, queryVector, null, null, null, "example-namespace", null, false, true); System.out.println("Dense query response:"); System.out.println(denseQueryResponse); // Query the index (sparse) with a metadata filter List sparseIndices = Arrays.asList( 767227209L, 1640781426L, 1690623792L, 2021799277L, 2152645940L, 2295025838L, 2443437770L, 2779594451L, 2956155693L, 3476647774L, 3818127854L, 428309169L); List sparseValues = Arrays.asList( 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f); QueryResponseWithUnsignedIndices sparseQueryResponse = sparseIndexConnection.query(1, null, sparseIndices, sparseValues, null, "example-namespace", null, false, true); System.out.println("Sparse query response:"); System.out.println(sparseQueryResponse); // Delete the indexes pc.deleteIndex(denseIndexName); pc.deleteIndex(sparseIndexName); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" "google.golang.org/protobuf/types/known/structpb" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() // Initialize a client. // No API key is required. // Host and port of the Pinecone Local instance // is required when starting without indexes. pc, err := pinecone.NewClientBase(pinecone.NewClientBaseParams{ Host: "http://localhost:5080", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // Create two indexes, one dense and one sparse denseIndexName := "dense-index" denseVectorType := "dense" dimension := int32(2) denseMetric := pinecone.Cosine deletionProtection := pinecone.DeletionProtectionDisabled denseIdx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: denseIndexName, VectorType: &denseVectorType, Dimension: &dimension, Metric: &denseMetric, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: &deletionProtection, Tags: &pinecone.IndexTags{"environment": "development"}, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", denseIdx.Name) } else { fmt.Printf("Successfully created serverless index: %v\n", denseIdx.Name) } sparseIndexName := "sparse-index" sparseVectorType := "sparse" sparseMetric := pinecone.Dotproduct sparseIdx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: sparseIndexName, VectorType: &sparseVectorType, Metric: &sparseMetric, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: &deletionProtection, Tags: &pinecone.IndexTags{"environment": "development"}, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", sparseIdx.Name) } else { fmt.Printf("\nSuccessfully created serverless index: %v\n", sparseIdx.Name) } // Get the index hosts denseIdxModel, err := pc.DescribeIndex(ctx, denseIndexName) if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", denseIndexName, err) } sparseIdxModel, err := pc.DescribeIndex(ctx, sparseIndexName) if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", sparseIndexName, err) } // Target the indexes. // Make sure to prefix the hosts with http:// to let the SDK know to disable tls. denseIdxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "http://" + denseIdxModel.Host, Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } sparseIdxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "http://" + sparseIdxModel.Host, Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } // Upsert records into the index (dense) denseMetadataMap1 := map[string]interface{}{ "genre": "drama", } denseMetadata1, err := structpb.NewStruct(denseMetadataMap1) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } denseMetadataMap2 := map[string]interface{}{ "genre": "documentary", } denseMetadata2, err := structpb.NewStruct(denseMetadataMap2) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } denseMetadataMap3 := map[string]interface{}{ "genre": "documentary", } denseMetadata3, err := structpb.NewStruct(denseMetadataMap3) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } denseVectors := []*pinecone.Vector{ { Id: "vec1", Values: &[]float32{1.0, -2.5}, Metadata: denseMetadata1, }, { Id: "vec2", Values: &[]float32{3.0, -2.0}, Metadata: denseMetadata2, }, { Id: "vec3", Values: &[]float32{0.5, -1.5}, Metadata: denseMetadata3, }, } denseCount, err := denseIdxConnection.UpsertVectors(ctx, denseVectors) if err != nil { log.Fatalf("Failed to upsert vectors: %v", err) } else { fmt.Printf("\nSuccessfully upserted %d vector(s)!\n", denseCount) } // Upsert records into the index (sparse) sparseValues1 := pinecone.SparseValues{ Indices: []uint32{822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191}, Values: []float32{1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688}, } sparseMetadataMap1 := map[string]interface{}{ "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones", "category": "technology", "quarter": "Q3", } sparseMetadata1, err := structpb.NewStruct(sparseMetadataMap1) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } sparseValues2 := pinecone.SparseValues{ Indices: []uint32{131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697}, Values: []float32{0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.560546}, } sparseMetadataMap2 := map[string]interface{}{ "chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4", } sparseMetadata2, err := structpb.NewStruct(sparseMetadataMap2) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } sparseValues3 := pinecone.SparseValues{ Indices: []uint32{8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697}, Values: []float32{2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094}, } sparseMetadataMap3 := map[string]interface{}{ "chunk_text": "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", "category": "technology", "quarter": "Q3", } sparseMetadata3, err := structpb.NewStruct(sparseMetadataMap3) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } sparseVectors := []*pinecone.Vector{ { Id: "vec1", SparseValues: &sparseValues1, Metadata: sparseMetadata1, }, { Id: "vec2", SparseValues: &sparseValues2, Metadata: sparseMetadata2, }, { Id: "vec3", SparseValues: &sparseValues3, Metadata: sparseMetadata3, }, } sparseCount, err := sparseIdxConnection.UpsertVectors(ctx, sparseVectors) if err != nil { log.Fatalf("Failed to upsert vectors: %v", err) } else { fmt.Printf("\nSuccessfully upserted %d vector(s)!\n", sparseCount) } // Check the number of records in each index denseStats, err := denseIdxConnection.DescribeIndexStats(ctx) if err != nil { log.Fatalf("Failed to describe index: %v", err) } else { fmt.Printf("\nIndex stats (dense): %+v\n", prettifyStruct(*denseStats)) } sparseStats, err := sparseIdxConnection.DescribeIndexStats(ctx) if err != nil { log.Fatalf("Failed to describe index: %v", err) } else { fmt.Printf("\nIndex stats (sparse): %+v\n", prettifyStruct(*sparseStats)) } // Query the index (dense) with a metadata filter queryVector := []float32{3.0, -2.0} queryMetadataMap := map[string]interface{}{ "genre": map[string]interface{}{ "$eq": "documentary", }, } metadataFilter, err := structpb.NewStruct(queryMetadataMap) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } denseRes, err := denseIdxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{ Vector: queryVector, TopK: 1, MetadataFilter: metadataFilter, IncludeValues: false, IncludeMetadata: true, }) if err != nil { log.Fatalf("Error encountered when querying by vector: %v", err) } else { fmt.Printf("\nDense query response: %v\n", prettifyStruct(denseRes)) } // Query the index (sparse) with a metadata filter sparseValues := pinecone.SparseValues{ Indices: []uint32{767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697}, Values: []float32{1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0}, } sparseRes, err := sparseIdxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{ SparseValues: &sparseValues, TopK: 1, IncludeValues: false, IncludeMetadata: true, }) if err != nil { log.Fatalf("Error encountered when querying by vector: %v", err) } else { fmt.Printf("\nSparse query response: %v\n", prettifyStruct(sparseRes)) } // Delete the indexes err = pc.DeleteIndex(ctx, denseIndexName) if err != nil { log.Fatalf("Failed to delete index: %v", err) } else { fmt.Printf("\nIndex \"%v\" deleted successfully\n", denseIndexName) } err = pc.DeleteIndex(ctx, sparseIndexName) if err != nil { log.Fatalf("Failed to delete index: %v", err) } else { fmt.Printf("\nIndex \"%v\" deleted successfully\n", sparseIndexName) } } ``` ```shell curl theme={null} PINECONE_LOCAL_HOST="localhost:5080" DENSE_INDEX_HOST="localhost:5081" SPARSE_INDEX_HOST="localhost:5082" # Create two indexes, one dense and one sparse curl -X POST "http://$PINECONE_LOCAL_HOST/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "dense-index", "vector_type": "dense", "dimension": 2, "metric": "cosine", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "tags": { "environment": "development" }, "deletion_protection": "disabled" }' curl -X POST "http://$PINECONE_LOCAL_HOST/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "sparse-index", "vector_type": "sparse", "metric": "dotproduct", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "tags": { "environment": "development" }, "deletion_protection": "disabled" }' # Upsert records into the index (dense) curl -X POST "http://$DENSE_INDEX_HOST/vectors/upsert" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "namespace": "example-namespace", "vectors": [ { "id": "vec1", "values": [1.0, -2.5], "metadata": {"genre": "drama"} }, { "id": "vec2", "values": [3.0, -2.0], "metadata": {"genre": "documentary"} }, { "id": "vec3", "values": [0.5, -1.5], "metadata": {"genre": "documentary"} } ] }' # Upsert records into the index (sparse) curl -X POST "http://$SPARSE_INDEX_HOST/vectors/upsert" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "namespace": "example-namespace", "vectors": [ { "id": "vec1", "sparseValues": { "values": [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688], "indices": [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191] }, "metadata": { "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "category": "technology", "quarter": "Q3" } }, { "id": "vec2", "sparseValues": { "values": [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469], "indices": [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697] }, "metadata": { "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4" } }, { "id": "vec3", "sparseValues": { "values": [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094], "indices": [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697] }, "metadata": { "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", "category": "technology", "quarter": "Q3" } } ] }' # Check the number of records in each index curl -X POST "http://$DENSE_INDEX_HOST/describe_index_stats" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{}' curl -X POST "http://$SPARSE_INDEX_HOST/describe_index_stats" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{}' # Query the index (dense) with a metadata filter curl "http://$DENSE_INDEX_HOST/query" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "vector": [3.0, -2.0], "filter": {"genre": {"$eq": "documentary"}}, "topK": 1, "includeMetadata": true, "includeValues": false, "namespace": "example-namespace" }' # Query the index (sparse) with a metadata filter curl "http://$SPARSE_INDEX_HOST/query" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "sparseVector": { "values": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0], "indices": [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697] }, "filter": {"quarter": {"$eq": "Q4"}}, "namespace": "example-namespace", "topK": 1, "includeMetadata": true, "includeValues": false }' # Delete the index curl -X DELETE "http://$PINECONE_LOCAL_HOST/indexes/dense-index" \ -H "X-Pinecone-Api-Version: 2025-10" curl -X DELETE "http://$PINECONE_LOCAL_HOST/indexes/sparse-index" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ## 2. Set up GitHub Actions [Set up a GitHub Actions workflow](https://docs.github.com/en/actions/writing-workflows/quickstart) to do the following: 1. Pull the Pinecone Local Docker image. 2. Start a Pinecone Local instance for each test run. 3. Execute tests against the local instance. 4. Tear down the instance after tests complete. Here's a sample GitHub Actions workflow that you can extend for your own needs: ```yaml theme={null} name: CI/CD with Pinecone Local on: pull_request: branches: - main push: branches: - main jobs: pc-local-tests: name: Pinecone Local tests runs-on: ubuntu-latest services: pc-local: image: ghcr.io/pinecone-io/pinecone-local:latest env: PORT: 5080 ports: - "5080-6000:5080-6000" steps: - name: Check out repository code uses: actions/checkout@v4 - name: Install dependencies run: | python -m pip install --upgrade pip pip install "pinecone[grpc]" - name: Run tests run: | pytest test/ ``` ## 3. Run your tests GitHub Actions will automaticaly run your tests against Pinecone Local when the events you specified in your workflow occur. For a list of the events that can trigger a workflow and more details about using GitHub Actions for CI/CD, see the [GitHub Actions documentation](https://docs.github.com/en/actions). # Bring your own cloud (BYOC) Source: https://docs.pinecone.io/guides/production/bring-your-own-cloud Deploy Pinecone BYOC in your own AWS, GCP, or Azure account for data sovereignty, network isolation, and regional data residency requirements. BYOC is in [public preview](/release-notes/feature-availability) on AWS, GCP, and Azure. Pinecone BYOC (bring your own cloud) is designed for organizations with strict requirements around data sovereignty, network isolation, and data residency. With BYOC, you deploy the Pinecone data plane in your own cloud account (AWS, GCP, or Azure), and you get the benefits of a managed service — upgrades, scaling, and maintenance — without giving up control of your data or infrastructure. Pinecone never has direct access to your cloud account. Your vectors, metadata, and queries never leave your environment, and no inbound network access is required. An agent in your cluster pulls operations from Pinecone and executes them locally. BYOC architecture diagram BYOC architecture diagram BYOC uses a split architecture: * The data plane runs entirely in your cloud account within a dedicated VPC, storing and processing your vectors, executing queries, and managing index data in object storage (S3 on AWS, GCS on GCP, or Azure Blob Storage on Azure). * The control plane is managed by Pinecone globally and handles index lifecycle management, authentication, billing, and user management, but never stores or processes your vectors. For maintenance, the agent authenticates with Pinecone's control plane, pulls pending operations (upgrades, scaling, etc.), and executes them locally. All operations are stored as Kubernetes CRDs, providing a complete audit trail. Only operational metrics (CPU, memory, latency) and traces are transmitted to Pinecone for monitoring; customer data is filtered out before transmission. ## Encryption and customer-managed keys In the **standard Pinecone service**, [customer-managed encryption keys (CMEK)](/guides/production/configure-cmek) are how you connect Pinecone-managed storage to **your** AWS KMS keys through the Pinecone console. In **BYOC**, your vectors and index data are stored in **your** cloud account (for example object storage, databases, and block volumes). You apply your cloud provider’s KMS to those resources using the same native controls you use for other workloads (key policies, rotation, and compliance programs such as PCI or ISO 27001). When you deploy with [pulumi-pinecone-byoc](https://github.com/pinecone-io/pulumi-pinecone-byoc), you can supply your KMS key where the template supports it; see that repository’s README for current options. This is not the console **CMEK** flow used for hosted projects. ## Prerequisites Before deploying BYOC, ensure you have the following tools installed on your local machine: | Tool | Purpose | Install | | ------------ | ---------------------- | ---------------------------------------------------------------------------- | | Python 3.12+ | Runtime | [python.org](https://www.python.org/downloads/) | | uv | Package manager | [docs.astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/) | | Pulumi | Infrastructure-as-code | [pulumi.com/docs/install](https://www.pulumi.com/docs/install/) | | kubectl | Cluster access | [kubernetes.io](https://kubernetes.io/docs/tasks/tools/) | You also need: * The CLI for your cloud provider: * **AWS**: [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) * **GCP**: [gcloud CLI](https://cloud.google.com/sdk/docs/install) * **Azure**: [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) * A cloud account with admin-level permissions: * **AWS**: `AdministratorAccess`. `PowerUserAccess` is not sufficient because BYOC creates IAM roles and policies. * **GCP**: `roles/owner`. `roles/editor` is not sufficient because BYOC creates IAM service accounts and bindings. * **Azure**: `Owner` on the subscription. `Contributor` is not sufficient because BYOC creates managed identities and role assignments. * Sufficient cloud quota for the resources (the setup wizard validates this) * A Pinecone API key from the Pinecone console. * A Pinecone Enterprise plan (required for BYOC access) If you install any new tools, open a new terminal session before proceeding so that your shell picks up the updated PATH and environment. ## Deploy BYOC To deploy BYOC, follow these steps: Run the bootstrap script from the BYOC deployment repository ([github.com/pinecone-io/pulumi-pinecone-byoc](https://github.com/pinecone-io/pulumi-pinecone-byoc)) to start the interactive setup wizard: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/pinecone-io/pulumi-pinecone-byoc/main/bootstrap.sh | bash ``` You can also pre-select your cloud provider: ```bash theme={null} # AWS curl -fsSL https://raw.githubusercontent.com/pinecone-io/pulumi-pinecone-byoc/main/bootstrap.sh | bash -s -- --cloud aws # GCP curl -fsSL https://raw.githubusercontent.com/pinecone-io/pulumi-pinecone-byoc/main/bootstrap.sh | bash -s -- --cloud gcp # Azure curl -fsSL https://raw.githubusercontent.com/pinecone-io/pulumi-pinecone-byoc/main/bootstrap.sh | bash -s -- --cloud azure ``` The script selects your cloud provider, checks that required tools are installed, verifies your cloud credentials, then launches an interactive wizard that collects your configuration choices, validates your quotas, and generates a Pulumi project. No cloud resources are created during this step. The wizard prompts you for the following: | Prompt | Description | Default | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | **Cloud provider** | Select AWS, GCP, or Azure (skipped if pre-selected via `--cloud`). | - | | **Pinecone API key** | Your API key from the Pinecone console (or uses `PINECONE_API_KEY` env var). | - | | **Cloud credentials** | Validates credentials and displays your account/project/subscription ID. | - | | **GCP project ID** | *(GCP only)* Your GCP project ID. | Detected from `gcloud` | | **Azure subscription ID** | *(Azure only)* Your Azure subscription ID. | Detected from `az account show` | | **Region** | Region for deployment. | `us-east-1` (AWS) / `us-central1` (GCP) / `eastus` (Azure) | | **Availability zones** | Zones for high availability. Wizard fetches available options. | First two zones | | **Custom AMI** | *(AWS only)* Custom AMI ID for EKS nodes. Leave blank for the default AWS AMI. | None | | **VPC CIDR block** | IP range for your VPC/VNet. Choose a range that doesn't conflict with existing networks. | `10.0.0.0/16` (AWS/Azure) / `10.112.0.0/12` (GCP) | | **Deletion protection** | Protect databases and storage from accidental deletion. | Enabled | | **Network access** | Public access (connect from anywhere) or private only (requires PrivateLink on AWS, Private Service Connect on GCP, or Private Link on Azure). | Public enabled | | **Resource tags/labels** | Custom tags (AWS/Azure) or labels (GCP) for cost tracking (e.g., `team=platform,env=prod`). | None | | **Preflight checks** | Validates cloud quotas. If checks fail, request quota increases before proceeding. | - | | **Project name** | Name for your deployment. | `pinecone-byoc` | | **Pulumi backend** | Where to store state: local (`~/.pulumi` with passphrase) or Pulumi Cloud. | Local | After completing the wizard, a Pulumi project is generated in your project directory. The wizard creates a `Pulumi..yaml` file with configurable options. The options vary by cloud provider: | Option | Description | Default | | ----------------------- | --------------------------------------------------- | ------------------------------ | | `pinecone-version` | Pinecone release version | - | | `region` | AWS region | `us-east-1` | | `availability-zones` | Availability zones for high availability | `["us-east-1a", "us-east-1b"]` | | `vpc-cidr` | VPC IP range | `10.0.0.0/16` | | `deletion-protection` | Protect RDS and S3 from accidental deletion | `true` | | `public-access-enabled` | Enable public endpoint (`false` = PrivateLink only) | `true` | | `custom-ami-id` | Custom AMI ID for EKS nodes | Default AWS AMI | | `tags` | Custom tags for all AWS resources | `{}` | | Option | Description | Default | | ----------------------- | --------------------------------------------------------------- | ------------------------------------ | | `gcp:project` | GCP project ID | - | | `pinecone-version` | Pinecone release version | - | | `region` | GCP region | `us-central1` | | `availability-zones` | Zones for high availability | `["us-central1-a", "us-central1-b"]` | | `vpc-cidr` | VPC IP range | `10.112.0.0/12` | | `deletion-protection` | Protect AlloyDB and GCS from accidental deletion | `true` | | `public-access-enabled` | Enable public endpoint (`false` = Private Service Connect only) | `true` | | `labels` | Custom labels for all GCP resources | `{}` | | Option | Description | Default | | ----------------------- | ----------------------------------------------------------------------- | ------------- | | `subscription-id` | Azure subscription ID | - | | `pinecone-version` | Pinecone release version | - | | `region` | Azure region | `eastus` | | `availability-zones` | Zones for high availability | `["1", "2"]` | | `vpc-cidr` | VNet IP range | `10.0.0.0/16` | | `deletion-protection` | Protect PostgreSQL Flexible Server and storage from accidental deletion | `true` | | `public-access-enabled` | Enable public endpoint (`false` = Private Link only) | `true` | | `tags` | Custom tags for all Azure resources | `{}` | To change configuration after initial setup, edit `Pulumi..yaml` and run `pulumi up`. For advanced users who want to integrate BYOC into existing Pulumi infrastructure, the `pulumi-pinecone-byoc` package is available on [PyPI](https://pypi.org/project/pulumi-pinecone-byoc/). Install with cloud-specific dependencies: ```bash theme={null} # For AWS uv add 'pulumi-pinecone-byoc[aws]' # For GCP uv add 'pulumi-pinecone-byoc[gcp]' # For Azure uv add 'pulumi-pinecone-byoc[azure]' ``` Import the cluster class for your cloud provider: ```python theme={null} # AWS from pulumi_pinecone_byoc.aws import PineconeAWSCluster, PineconeAWSClusterArgs # GCP from pulumi_pinecone_byoc.gcp import PineconeGCPCluster, PineconeGCPClusterArgs # Azure from pulumi_pinecone_byoc.azure import PineconeAzureCluster, PineconeAzureClusterArgs ``` See the [repository README](https://github.com/pinecone-io/pulumi-pinecone-byoc#programmatic-usage) for full usage examples. Deploy the generated Pulumi project to create your cloud resources: ```bash theme={null} cd pinecone-byoc pulumi up ``` Pulumi shows a preview of all resources to be created. Confirm to proceed. Provisioning takes approximately 25-30 minutes. When complete, the output displays: * Your BYOC **environment name** (used when creating indexes). * The **kubectl command** to configure cluster access. The deployment creates the following resources in your cloud account: | Component | AWS | GCP | Azure | | -------------------- | --------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------ | | **VPC / Networking** | VPC, public and private subnets, NAT gateways, internet gateway | VPC network, subnets, Cloud NAT, Cloud Router | VNet, subnets, NAT gateway | | **Kubernetes** | EKS cluster with managed node groups | GKE cluster with node pools | AKS cluster with agent pools | | **Object storage** | S3 buckets (data, WAL, backups) | GCS buckets (data, WAL, backups) | Blob Storage containers (data, WAL, backups) | | **Database** | Aurora PostgreSQL (RDS) | AlloyDB | PostgreSQL Flexible Server | | **Load balancing** | Network Load Balancer | Internal load balancer with Private Service Connect | Internal load balancer with Private Link Service | | **DNS** | Route 53 hosted zone | Cloud DNS managed zone | Azure DNS zone | | **TLS certificates** | AWS Certificate Manager | cert-manager | cert-manager | | **IAM** | IAM roles and policies | Service accounts and Workload Identity | Managed identities and Workload Identity | The initial deployment provisions 3 Kubernetes nodes. After setup, the cluster autoscales based on the services Pinecone deploys and your workload. Configure `kubectl` to connect to your cluster using the command from the deployment output: ```bash theme={null} aws eks update-kubeconfig --region --name ``` ```bash theme={null} gcloud container clusters get-credentials --region --project ``` ```bash theme={null} az aks get-credentials --resource-group --name ``` The above command configures your local `kubectl` tool to communicate with your Kubernetes cluster. You'll use cluster access for administrative tasks like viewing operations and troubleshooting. Creating indexes and reading/writing vectors still use the standard Pinecone API. Verify all components are running: ```bash theme={null} # Check that all pods are running kubectl get pods -A | grep -E "(pinecone|pc-)" ``` All pods should show `Running` status. If any pods are in `Pending` or `CrashLoopBackOff`, check the [Troubleshooting](#troubleshooting) section. You can also verify the cluster operations CRD is installed: ```bash theme={null} kubectl get cluster-operations ``` It's normal to see "No resources found" on a fresh deployment. Operations appear here as Pinecone performs upgrades and other management tasks. ## Use BYOC Once your BYOC environment is deployed, you can create indexes and read/write data using the standard Pinecone API. ### Control plane operations Control plane operations like [creating](/reference/api/latest/control-plane/create_index), [listing](/reference/api/latest/control-plane/list_indexes), and [deleting](/reference/api/latest/control-plane/delete_index) indexes work via the standard Pinecone API regardless of your network access mode. BYOC supports [dedicated read nodes](/guides/index-data/dedicated-read-nodes) indexes, but not on-demand indexes. Use the environment name from the deployment output to create indexes in your BYOC environment. BYOC supports [dedicated read nodes](/guides/index-data/dedicated-read-nodes) indexes only. ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -X POST "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "example-byoc-index", "dimension": 1536, "metric": "cosine", "vector_type": "dense", "spec": { "byoc": { "environment": "aws-us-east-1-26bf.byoc", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 1, "replicas": 1 } } } } }, "deletion_protection": "disabled" }' ``` ```python Python theme={null} from pinecone import Pinecone from pinecone.db_control.models import ByocSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.db.index.create( name="example-byoc-index", dimension=1536, metric="cosine", vector_type="dense", spec=ByocSpec( environment="aws-us-east-1-26bf.byoc", read_capacity={ "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 1, "replicas": 1, }, }, }, ), deletion_protection="disabled", ) ``` ### Data plane operations Data plane operations like [querying](/reference/api/latest/data-plane/query), [upserting](/reference/api/latest/data-plane/upsert), and [fetching](/reference/api/latest/data-plane/fetch) vectors depend on your network access mode. BYOC does not support reading and writing data from the index browser in the Pinecone console. Use the `host` URL from the Pinecone console or the [Describe an index](/reference/api/latest/control-plane/describe_index) API response. For example: ``` https://my-index-abc123.svc.us-east-1.byoc.pinecone.io ``` Connect from anywhere using the standard Pinecone SDK or API. With public access disabled, you can only connect from within your VPC via private connectivity. You cannot use the Pinecone console for data plane operations (query, upsert, fetch), though control plane operations (create, delete, list indexes) still work. After deployment, the Pulumi stack outputs include the service name needed to create a private endpoint for your cloud provider. Use this service name to set up private connectivity: Follow the instructions in the AWS documentation to [create a VPC endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#create-interface-endpoint-aws) for connecting to your indexes via AWS PrivateLink. For **Resource configurations**, use the VPC endpoint service name from the Pulumi stack outputs. For **Network settings**, select the VPC for your BYOC deployment. In **Additional settings**, select **Enable DNS name** to allow you to access your indexes using a DNS name. Follow the instructions in the GCP documentation to [create a private endpoint](https://cloud.google.com/vpc/docs/configure-private-service-connect-services#create-endpoint) for connecting to your indexes via GCP Private Service Connect. * Set the **Target service** to the service attachment from the Pulumi stack outputs. * Copy the IP address of the private endpoint. You'll need it later. Follow the instructions in the GCP documentation to [create a private DNS zone](https://cloud.google.com/dns/docs/zones#create-private-zone). * Set the **DNS name** to the following: ``` .byoc.pinecone.io ``` * Select the same VPC network as the private endpoint. Follow the instructions in the GCP documentation to [add a resource record set](https://cloud.google.com/dns/docs/records#add-rrset). * Set the **DNS name** to **\***. * Set the **Resource record type** to **A**. * Set the **Ipv4 Address** to the IP address of the private endpoint. Follow the instructions in the Azure documentation to [create a private endpoint](https://learn.microsoft.com/en-us/azure/private-link/create-private-endpoint-portal) for connecting to your indexes via Azure Private Link. * Set the **Resource type** to `Microsoft.Network/privateLinkServices`. * Select the Private Link Service name from the Pulumi stack outputs. * Copy the IP address of the private endpoint. You'll need it later. Follow the instructions in the Azure documentation to [create a private DNS zone](https://learn.microsoft.com/en-us/azure/dns/private-dns-getstarted-portal). * Set the **Name** to the following: ``` .byoc.pinecone.io ``` * Link the zone to the VNet containing the private endpoint. Follow the instructions in the Azure documentation to [add a record set](https://learn.microsoft.com/en-us/azure/dns/private-dns-getstarted-portal#create-an-additional-dns-record). * Set the **Name** to **\***. * Set the **Type** to **A**. * Set the **IP address** to the IP address of the private endpoint. Once configured, use the `private_host` URL from the Pinecone console or the [Describe an index](/reference/api/latest/control-plane/describe_index) API response. For example: ``` https://my-index-abc123.svc.private.us-east-1.byoc.pinecone.io ``` ## Manage BYOC ### Operations and upgrades Pinecone uses a pull-based model for cluster operations: 1. When upgrades, scaling, or maintenance are needed, Pinecone queues operations in the control plane. 2. An agent running in your cluster (deployed automatically during setup) continuously pulls pending operations. 3. Operations execute locally within your cluster. 4. Status is reported back to Pinecone for monitoring. This model ensures Pinecone never needs direct access to your infrastructure. All operations are stored as Kubernetes CRDs, providing a complete audit trail. ### Monitoring You can monitor your BYOC deployment through multiple channels: View index metrics (read/write units, latency, storage) in the Pinecone console. Control plane operations and metrics work regardless of your network access mode. To use Prometheus, configure your monitoring tool within your VPC to scrape metrics from the cluster. Your Prometheus instance must have network access to the BYOC VPC. The deployment output includes the metrics endpoint URL and port for configuration. All cluster operations are persisted as Kubernetes CRDs for compliance and auditing: ```bash theme={null} kubectl get cluster-operations ``` ### Cleanup To destroy your BYOC deployment: Delete all BYOC indexes before destroying the cluster. Indexes cannot be properly terminated if the cluster is destroyed first. ```bash theme={null} # 1. Delete all indexes via Pinecone API or console # 2. Then destroy the infrastructure pulumi destroy ``` If `deletion_protection` is enabled (the default), you must either disable it in `Pulumi..yaml` and run `pulumi up`, or manually delete protected resources via the cloud console before running `pulumi destroy`: * **AWS**: RDS instances and S3 buckets * **GCP**: AlloyDB instances and GCS buckets * **Azure**: PostgreSQL Flexible Server instances and Storage accounts ## Reference ### Troubleshooting Common issues and how to resolve them: The setup wizard validates cloud quotas before deployment. If checks fail: | Check | Resolution | | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | VPC / network quota | Request a limit increase via your cloud provider's quota console | | Kubernetes cluster quota | Request an EKS, GKE, or AKS cluster limit increase | | IP address quota | Release unused IPs or request a limit increase | | Instance / machine type availability | Verify the required type is available in your region | | vCPU quota (Azure) | Request a "Total Regional vCPUs" increase via the Azure Portal (minimum 8 required) | | VM SKU availability (Azure) | Verify `Standard_D4s_v5` and L-series SKUs are available in your region | | Resource providers (Azure) | Register required providers: `Microsoft.Compute`, `Microsoft.ContainerService`, `Microsoft.DBforPostgreSQL`, `Microsoft.Storage`, `Microsoft.Network`, `Microsoft.KeyVault`, `Microsoft.ManagedIdentity`, `Microsoft.Authorization` | | Required APIs (GCP only) | Enable Compute Engine, GKE, AlloyDB, Cloud Storage, and Cloud DNS | If `pulumi up` fails partway through: ```bash theme={null} pulumi refresh # Sync state with actual resources pulumi up # Retry deployment ``` Ensure your cloud credentials match the account where the cluster is deployed: ```bash theme={null} aws sts get-caller-identity ``` ```bash theme={null} gcloud auth list gcloud config get-value project ``` ```bash theme={null} az account show ``` If you destroyed the cluster before deleting indexes, indexes may be stuck in a "terminating" state. Contact [Pinecone support](https://app.pinecone.io/organizations/-/settings/support/ticket) for assistance. For additional help, see the [GitHub Issues](https://github.com/pinecone-io/pulumi-pinecone-byoc/issues) for the deployment repository. ### Limitations Some features available in the standard Pinecone service are not yet supported or have constraints in BYOC: * Each organization can have up to 2 BYOC environments. To request an increase, contact [Pinecone support](https://app.pinecone.io/organizations/-/settings/support/ticket). * [Integrated embedding and inference](/guides/index-data/indexing-overview#integrated-embedding), which relies on models hosted by Pinecone outside your cloud account. * Reading and writing data from the index browser in the Pinecone console. * Pinecone CLI data plane operations (queries, upserts, fetches). Control plane operations (create, list, delete indexes) work as expected. * Imports from private cloud storage buckets, unless the bucket is in the same cloud account as your BYOC deployment. * On-demand indexes (initial release supports DRN indexes only). To [monitor with Prometheus](/guides/production/monitoring#monitor-with-prometheus), you must configure Prometheus within your VPC. ### FAQs Answers to common questions about BYOC: No. BYOC is designed so Pinecone never needs direct access to your infrastructure. Specifically: * Pinecone does not need SSH, VPN, or inbound access to your cluster. * You control cloud account boundaries, networking, and Kubernetes access. * Operational changes run through explicit, software-mediated workflows. * You don't open inbound firewall ports for Pinecone operations. Operations are executed via a pull-based model where your cluster retrieves and runs operations locally. All communication is outbound from your cluster. **Does not leave your cloud account:** * Vectors, metadata, and index contents * Query and upsert payloads * Customer data **Can leave your cloud account:** * Operational metrics and traces (for example, CPU, memory, latency) * Cluster health and operation status Customer data is filtered out before transmission and never leaves your cloud account. In the standard service, Pinecone manages all cloud resources and includes their cost in the service fee. In BYOC, you provision and pay for cloud resources directly through your own cloud account, providing greater control, data sovereignty, and access to available cloud credits or discounts. You use API keys from the Pinecone console, just like with the standard Pinecone service. Authentication is handled by Pinecone's global control plane, and your data plane caches API keys locally. This means you manage users and API keys through the console as usual. Data is stored and processed exclusively within your cloud account, with encryption at rest and in transit. You control at-rest encryption for the underlying resources (including KMS keys in your account) the same way you do for other infrastructure. Communication between the data plane and control plane is encrypted using TLS. Private connectivity (AWS PrivateLink, GCP Private Service Connect, or Azure Private Link) can be used for additional network isolation. For how this relates to hosted [CMEK](/guides/production/configure-cmek), see [Encryption and customer-managed keys](#encryption-and-customer-managed-keys). BYOC is available on AWS, GCP, and Azure. Indexes cannot be properly terminated if the cluster is destroyed first. Always delete indexes via the Pinecone API or console before running `pulumi destroy`. Deploying a BYOC environment creates an internal project named `__SLI__` in your organization. This is used by Pinecone to enforce SLAs for your BYOC environment. Do not modify or delete this project. ### Pricing BYOC pricing is based on provisioned resources (compute and storage) in your deployment, metered over time. Usage is measured by the Pinecone BYOC agent running in your cluster, which periodically reports the resources that are provisioned. What you pay: * Pinecone fees: Based on provisioned compute (vCPU and RAM) and storage (NVMe) resources * Cloud provider fees: You pay your cloud provider directly for the underlying infrastructure (Kubernetes nodes, object storage, databases, networking, etc.) Billing follows the agent heartbeat connection to Pinecone's control plane: * When heartbeats are received, you are billed for the provisioned compute and storage the agent reports, even if the cluster is unhealthy. * Short heartbeat interruptions (under 60 minutes) are treated as a grace period. * If heartbeats are missing for more than 60 minutes, billing stops and the deployment is marked disconnected. Billing is based on provisioned resources, not query volume. Resources that are running in your cluster are billed whether they are idle, actively processing queries, or experiencing errors. # Configure audit logs Source: https://docs.pinecone.io/guides/production/configure-audit-logs Enable Pinecone audit logging to an Amazon S3 bucket to track user, service account, and API actions for compliance, security review, and WORM retention. This page describes how to configure audit logs in Pinecone. Audit logs provide a detailed record of user, service account, and API actions that occur on the management and [control plane](/guides/get-started/database-architecture#control-plane) within Pinecone. Pinecone supports Amazon S3 as a destination for audit logs. To enable and manage audit logs, you must be an [organization owner](/guides/organizations/understanding-organizations#organization-roles). This feature is available only on [Enterprise plans](https://www.pinecone.io/pricing/). ## Enable audit logs 1. Set up a [IAM policy and role in Amazon S3](/guides/operations/integrations/integrate-with-amazon-s3). 2. Go to [**Settings > Audit logs**](https://app.pinecone.io/organizations/-/settings/logging) in the Pinecone console. 3. Enter the **Role ARN** of the IAM role you created. 4. Enter the name of the Amazon S3 bucket you created. **Targeting a subdirectory:** You can write audit logs to a specific subdirectory by entering `bucket-name/subdirectory-path` in the bucket name field. For example: `my-bucket/pinecone-logs`. Make sure your [IAM policy is configured for subdirectory access](/guides/operations/integrations/integrate-with-amazon-s3#targeting-a-subdirectory-optional). 5. Click **Enable audit logging**. Once you enable audit logs, Pinecone will start writing logs to the S3 bucket. In your bucket, you will also see a file named `audit-log-access-test`, which is a test file that Pinecone writes to verify that it has the necessary permissions to write logs to the bucket. ## Make your audit-log bucket immutable (recommended) Because audit logs are written to an Amazon S3 bucket you control, you can enforce write-once-read-many (WORM) immutability so that log files cannot be modified or deleted — including by your own administrators — for a retention period you define. This is recommended for compliance use cases. Enable [S3 Object Lock](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock.html) in **compliance mode** with a retention period. Object Lock requires bucket versioning and, in general, must be enabled when the bucket is created — plan for it when you set up the [IAM policy and S3 bucket](/guides/operations/integrations/integrate-with-amazon-s3) above. Set the retention period to at least your required audit-log retention. Pinecone writes each log batch as a new, uniquely named file and does not modify or delete previously written logs. Compliance mode is intentionally irreversible: until a retention period expires, objects cannot be deleted and the period cannot be shortened — not even by the root account. Logs already written to the bucket are therefore retained for the full period even if you later disable or remove the audit log integration. ## View audit logs Logs are written to the S3 bucket approximately every 30 minutes. Each log batch will be saved into its own file as a JSON blob, keyed by the time of the log to be written. Only logs since the integration was created and enabled will be saved. For more information about the log schema and captured events, see [Understanding security - Audit logs](/guides/production/security-overview#audit-logs). ## Edit audit log integration details You can edit the details of the audit log integration in the Pinecone console: 1. Go to [**Settings > Audit logs**](https://app.pinecone.io/organizations/-/settings/logging). 2. Enter the new **Role ARN** or **AWS Bucket**. 3. Click **Update settings**. ## Disable audit logs If you disable audit logs, logs not yet saved will be lost. You can disable audit logs in the Pinecone console: 1. Go to [**Settings > Audit logs**](https://app.pinecone.io/organizations/-/settings/logging). 2. Click the toggle next to **Audit logs are active**. 3. Click **Confirm**. ## Remove audit log integration If you remove the audit log integration, logs not yet saved will be lost. You can remove the audit log integration in the Pinecone console: 1. Go to [**Settings > Audit logs**](https://app.pinecone.io/organizations/-/settings/logging). 2. At the top of the page, click the **ellipsis (...) menu > Remove integration**. 3. Click **Remove integration**. # Configure customer-managed encryption keys Source: https://docs.pinecone.io/guides/production/configure-cmek Set up customer-managed encryption keys (CMEK) with AWS KMS to encrypt Pinecone data with keys you control, using IAM roles and key policies. This guide applies to **hosted** Pinecone projects where Pinecone manages your infrastructure. If you use [Bring your own cloud (BYOC)](/guides/production/bring-your-own-cloud), you encrypt data with **your** cloud provider KMS on resources in **your** account; follow the BYOC guide and [pulumi-pinecone-byoc](https://github.com/pinecone-io/pulumi-pinecone-byoc) instead of the console CMEK flow below. This page describes how to set up and use customer-managed encryption keys (CMEK) to secure data within a Pinecone project. CMEK allows you to encrypt your data using keys that you manage in your cloud provider's key management system (KMS). Pinecone supports CMEK using Amazon Web Services (AWS) KMS. ## Set up CMEK using AWS KMS ### Before you begin The following steps assume you have: * Access to the [AWS console](https://console.aws.amazon.com/console/home). * A [Pinecone Enterprise plan](https://www.pinecone.io/pricing/). ### 1. Create a role In the [AWS console](https://console.aws.amazon.com/console/home), create a role that Pinecone can use to access the AWS Key Management System (KMS) key. You can either grant Pinecone access to a key in your account, or if your customers provide their own keys, you can grant access to keys that are outside of your account. 1. Open the [Amazon Identity and Access Management (IAM) console](https://console.aws.amazon.com/iam/). 2. In the navigation pane, click **Roles**. 3. Click **Create role**. 4. In the **Trusted entity type** section, select **Custom trust policy**. 5. In the **Custom trust policy** section, enter one of the following JSON snippets. Pick a snippet based on whether you want to allow Pinecone to assume a role from all regions or from explicit regions. Add an optional external ID for additional security. If you use an external ID, you must provide it to Pinecone when [adding a CMEK key](#add-a-key). ```jsonc JSON theme={null} { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowPineconeToAssumeIntoRoleFromExplicitRegionswithID", "Effect": "Allow", "Principal": { "AWS": [ // Explicit role per Pinecone region. Replace XXXXXXXXXXXX with Pinecone's AWS account number. "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_us-east-1", "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_us-west-2", "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_eu-west-1", "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_eu-central-1", "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_ap-southeast-1" ] }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { // Optional. Replace with a UUID v4 for additional security. If you use an external ID, you must provide it to Pinecone when adding an API key. "sts:ExternalId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" } } } ] } ``` ```jsonc JSON theme={null} { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowPineconeToAssumeIntoRoleFromExplicitRegions", "Effect": "Allow", "Principal": { "AWS": [ // Explicit role per Pinecone region. Replace XXXXXXXXXXXX with Pinecone's AWS account number. "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_us-east-1", "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_us-west-2", "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_eu-west-1", "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_eu-central-1", "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_ap-southeast-1" ] }, "Action": "sts:AssumeRole" } ] } ``` ```jsonc JSON theme={null} { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowPineconeToAssumeIntoRoleFromAllRegions", "Effect": "Allow", "Principal": { "AWS": "*" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { // Optional. Replace with a UUID v4 for additional security. If you use an external ID, you must provide it to Pinecone when adding an API key. "sts:ExternalId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" }, "StringLike": { // Replace XXXXXXXXXXXX with Pinecone's AWS account number. "aws:PrincipalArn": "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_*" } } } ] } ``` Replace `XXXXXXXXXXXX` with Pinecone's AWS account number, which can be found by going to [**Manage > CMEK**](https://app.pinecone.io/organizations/-/projects/-/cmek-encryption) in the Pinecone console and clicking **Add CMEK**. 6. Click **Next**. 7. Keep the default permissions as is and click **Next**. 8. Enter a **Role name** and click **Create role**. 9. Copy the **Role ARN** (e.g., `arn:aws:iam::XXXXXX:role/YYYYYY`). This will be used to [create a CMEK-enabled project](#3-create-a-cmek-enabled-project). 1. Open the [Amazon Identity and Access Management (IAM) console](https://console.aws.amazon.com/iam/). 2. In the navigation pane, click **Roles**. 3. Click **Create role**. 4. In the **Trusted entity type** section, select **Custom trust policy**. 5. In the **Custom trust policy** section, enter the following JSON: ```json JSON theme={null} { "Version": "2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": [ "kms:Decrypt", "kms:Encrypt" ], "Resource": "arn:aws:kms:*:XXXXXX:key/*" } ] } ``` * Replace `XXXXXX` with the account ID of the customer who owns the key. * Add a `Statement` array for each customer account ID. 6. Click **Next**. 7. Keep the default permissions as is and click **Next**. 8. Enter a **Role name** and click **Create role**. 9. Copy the **Role ARN** (e.g., `arn:aws:iam::XXXXXX:role/YYYYYY`). This will be used to [create a CMEK-enabled project](#3-create-a-cmek-enabled-project). ### 2. Create an AWS KMS key In the [AWS console](https://console.aws.amazon.com/console/home), create the KMS key that Pinecone will use to encrypt your data: 1. Open the [Amazon Key Management Service (KMS) console](https://console.aws.amazon.com/kms/home). 2. In the navigation pane, click **Customer managed keys**. 3. Click **Create key**. 4. In the **Key type** section, select **Symmetric**. 5. In the **Key usage** section, select **Encrypt and decrypt**. 6. Under **Advanced options > Key material origin**, select **KMS**. 7. In the **Regionality** section, select **Single-Region key**. You can create a multi-regional key to safeguard against data loss in case of regional failure. However, Pinecone only accepts one Key ARN per project. If you set a multi-regional key and need to change the Key ARN to switch region, please [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) for help. 8. Click **Next**. 9. Enter an **Alias** and click **Next**. 10. Keep the default administrators as is and click **Next**. 11. Select the [role you created](#1-create-a-role) from the **Key users** list and click **Next**. 12. Click **Finish**. 13. Copy the **Key ARN** (e.g., `arn:aws:kms:us-east-1:XXXXXXX:key/YYYYYYY`). This will be used to [create a CMEK-enabled project](#create-a-cmek-enabled-project). **AWS KMS automatic key rotation is supported.** Pinecone references the Key ARN, not the underlying key material. As long as the Key ARN remains unchanged and accessible, you can perform key rotations inside AWS KMS without making any changes in Pinecone. ### 3. Create a CMEK-enabled project Once your [role and key is configured](#set-up-cmek-using-aws-kms), you can create a CMEK-enabled project using the Pinecone console: 1. Go to [**Settings > Organization settings > Projects**](https://app.pinecone.io/organizations/-/settings/projects). 2. Click **+Create project**. 3. Enter a **Name**. 4. Select **Encrypt with Customer Managed Encryption Key**. 5. Click **Create project**. 6. Copy and save the generated API key in a secure place for future use. You will not be able to see the API key again after you close the dialog. 7. Click **Close**. ## Add a key To start encrypting your data with a customer-managed key, you need to add the key to the [CMEK-enabled project](#3-create-a-cmek-enabled-project) using the Pinecone console: 1. Go to [**Manage > CMEK**](https://app.pinecone.io/organizations/-/projects/-/cmek-encryption) for the CMEK-enabled project. 2. Click **Add CMEK**. You can only add one key per project, and you cannot change the key in Pinecone once it is set. 3. Enter a **Key name**. 4. Enter the **Role ARN** for the [role you created](#1-create-a-role). 5. Enter a **Key ARN** for the [key you created](#2-create-a-aws-kms-key). 6. If you [created a role](#1-create-a-role) with an external ID, enter the **External ID**. If not, leave this field blank. 7. Click **Create key**. ## Delete a key Before a key can be deleted from a project, all indexes in the project must be deleted. Then, you can delete the key using the Pinecone console: 1. Go to the [Manage > CMEK tab](https://app.pinecone.io/organizations/-/projects/-/cmek-encryption) for the project in which the key was created. 2. For the key you want to delete, click the **ellipsis (...) menu > Delete**. 3. Enter the key name to confirm deletion. 4. Click **Delete key**. ## Limitations * CMEK can be enabled for serverless indexes in AWS regions only. * [Backups](/guides/manage-data/back-up-an-index) are unavailable for indexes created in a CMEK-enabled project. * You cannot change a key once it is set. * You can add only one key per project. # Configure Private Endpoints Source: https://docs.pinecone.io/guides/production/configure-private-endpoints Configure Pinecone Private Endpoints with AWS PrivateLink or Azure Private Link to keep index traffic off the public internet and secure VPCs. This page describes how to create and use [Private Endpoints](/guides/production/security-overview#private-endpoints) to connect to Pinecone through AWS PrivateLink or Azure Private Link, keeping your traffic private from the public internet. ## Use Private Endpoints with Pinecone ### Before you begin The following steps assume you have: * Access to the [AWS console](https://console.aws.amazon.com/console/home). * [Created an Amazon VPC](https://docs.aws.amazon.com/vpc/latest/userguide/create-vpc.html#create-vpc-and-other-resources) in the same AWS [region](/guides/index-data/create-an-index#cloud-regions) as the index you want to connect to. You can optionally enable DNS hostnames and resolution, if you want your VPC to automatically discover the DNS CNAME for your PrivateLink and do not want to configure a CNAME. * To [configure the routing](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-vpc-interface-endpoint.html) yourself, use one of Pinecone's DNS entry for the corresponding region: | Index region | Pinecone DNS entry | | ---------------------------- | -------------------------------------- | | `us-east-1` (N. Virginia) | `*.private.aped-4627-b74a.pinecone.io` | | `us-west-2` (Oregon) | `*.private.apw5-4e34-81fa.pinecone.io` | | `eu-west-1` (Ireland) | `*.private.apu-57e2-42f6.pinecone.io` | | `eu-central-1` (Frankfurt) | `*.private.apec-a2ee-38c6.pinecone.io` | | `ap-southeast-1` (Singapore) | `*.private.aps-d9bb-582b.pinecone.io` | * Access to the [Azure portal](https://portal.azure.com). * [Created an Azure VNet](https://learn.microsoft.com/en-us/azure/virtual-network/quick-create-portal) in the same [region](/guides/index-data/create-an-index#cloud-regions) as the index you want to connect to. * A subnet with **Private endpoint network policies** set to **Disabled**. This is required for Azure Private Endpoints. * DNS resolution for private endpoints requires a manual setup step after creating the endpoint (unlike AWS, where DNS can be auto-configured). See the [DNS setup note below](#1-create-a-private-endpoint-in-your-cloud-provider). | Index region | Pinecone DNS entry | | -------------------- | ----------------------------------------------- | | `eastus2` (Virginia) | `*.private.eastus2-5e25.prod-azure.pinecone.io` | * A [Pinecone Enterprise plan](https://www.pinecone.io/pricing/). * [Created a serverless index](/guides/index-data/create-an-index#create-a-serverless-index) in the same [region](/guides/index-data/create-an-index#cloud-regions) as your VPC or VNet. Private Endpoints are configured at the project-level and you can add up to 10 endpoints per project. If you have multiple projects in your organization, Private Endpoints need to be set up separately for each. ### 1. Create a private endpoint in your cloud provider In the [AWS console](https://console.aws.amazon.com/console/home): 1. Open the [Amazon VPC console](https://console.aws.amazon.com/vpc/). 2. In the navigation pane, click **Endpoint**. 3. Click **Create endpoint**. 4. For **Service category**, select **Other endpoint services**. 5. In **Service settings**, enter the **Service name**, based on the region your Pinecone index is in: | Index region | Service name | | ---------------------------- | -------------------------------------------------------------- | | `us-east-1` (N. Virginia) | `com.amazonaws.vpce.us-east-1.vpce-svc-05ef6f1f0b9130b54` | | `us-west-2` (Oregon) | `com.amazonaws.vpce.us-west-2.vpce-svc-04ecb9a0e0d5aab01` | | `eu-west-1` (Ireland) | `com.amazonaws.vpce.eu-west-1.vpce-svc-03c6b7e17ff02a70f` | | `eu-central-1` (Frankfurt) | `com.amazonaws.vpce.eu-central-1.vpce-svc-037997ff6b3d25e34` | | `ap-southeast-1` (Singapore) | `com.amazonaws.vpce.ap-southeast-1.vpce-svc-0c12f00812e786068` | 6. Click **Verify service**. 7. Select the **VPC** to host the endpoint. 8. (Optional) In **Additional settings**, **Enable DNS name**. The enables you to access our service with the DNS name we configure. An additional CNAME record is needed if you disable this option. 9. Select the **Subnets** and **Subnet ID** for the endpoint. 10. Select the **Security groups** to apply to the endpoint. 11. Click **Create endpoint**. 12. Copy the **VPC endpoint ID** (e.g., `vpce-XXXXXXX`). This will be used to [add a Private Endpoint in Pinecone](#2-add-a-private-endpoint-in-pinecone). In the [Azure portal](https://portal.azure.com): 1. Search for **Private Link** and select **Private Link Center**. 2. In the navigation pane, click **Private endpoints**. 3. Click **Create**. 4. Select your **Subscription** and **Resource group**. 5. Enter a **Name** for the private endpoint and select the **Region** matching your Pinecone index. 6. Click **Next: Resource**. 7. For **Connection method**, select **Connect to an Azure resource by resource ID or alias**. 8. Enter the **Resource ID or alias** for Pinecone's Private Link Service, based on the region your Pinecone index is in: | Index region | Private Link Service alias | | -------------------- | -------------------------------------------------------------------------------- | | `eastus2` (Virginia) | `pinecone.bdbc7759-0243-46c1-af51-794c4602745b.eastus2.azure.privatelinkservice` | 9. Click **Next: Virtual Network**. 10. Select the **Virtual network** and **Subnet** for the private endpoint. 11. Click **Next: DNS**. Skip the DNS integration tab (you will configure DNS manually after setup). 12. Click **Next: Tags**. 13. Click **Review + create**, then **Create**. 14. Once the private endpoint is created, open it and copy the **Resource ID** from the **Properties** tab (or the **Overview** tab — it's the `/subscriptions/…/privateEndpoints/` ARM ID). This will be used to [add a Private Endpoint in Pinecone](#2-add-a-private-endpoint-in-pinecone). After creating the private endpoint, configure DNS so that `*.private.{subdomain}.pinecone.io` resolves to your private endpoint's IP address: 1. Find your private endpoint's IP address: in the Azure portal, open your private endpoint, go to **Overview**, and note the **Private IP address** (e.g., `172.30.0.6`). 2. Create an [Azure Private DNS Zone](https://learn.microsoft.com/en-us/azure/dns/private-dns-getstarted-portal) named `private.{subdomain}.pinecone.io` (e.g., `private.eastus2-5e25.prod-azure.pinecone.io`). You can find the `{subdomain}` in your index's host URL — it's the portion after `svc.` and before `.pinecone.io`. 3. [Link the zone](https://learn.microsoft.com/en-us/azure/dns/private-dns-virtual-network-links) to the VNet where your private endpoint is created. 4. Add a **wildcard A record** (`*`) pointing to your private endpoint's IP address. ### 2. Add a Private Endpoint in Pinecone To add a Private Endpoint using the [Pinecone console](https://app.pinecone.io/organizations/-/projects): 1. Select your project. 2. Go to **Manage > Network**. 3. Click **Add a connection**. 4. Select your cloud provider and region. Only indexes in the selected region in this project will be affected. 5. Click **Next**. 6. Enter the endpoint ID you copied in the [section above](#1-create-a-private-endpoint-in-your-cloud-provider): * **AWS**: The VPC endpoint ID (e.g., `vpce-XXXXXXX`) * **Azure**: The private endpoint's ARM Resource ID (e.g., `/subscriptions//resourceGroups//providers/Microsoft.Network/privateEndpoints/`) 7. Click **Next**. 8. (optional) To **enable private endpoint access only**, turn the toggle on. This can also be enabled later. For more information, see [Manage internet access to your project](#manage-internet-access-to-your-project). 9. Click **Finish setup**. Private Endpoints only affect [data plane](/reference/api/latest/data-plane) access. [Control plane](/reference/api/latest/control-plane) access will continue over the public internet. ## Read and write data Once your private endpoint is configured, you can run data operations against an index as usual, but you must target the index using its private endpoint URL. The only difference in the URL is that `.svc.` is changed to `.svc.private.`. You can get the private endpoint URL for an index from the Pinecone console or API. To get the private endpoint URL for an index from the Pinecone console: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select the project containing the index. 3. Select the index. 4. Copy the URL under **PRIVATE ENDPOINT**. To get the private endpoint URL for an index from the API, use the [`describe_index`](/reference/api/latest/control-plane/describe_index) operation, which returns the private endpoint URL as the `private_host` value: ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.describeIndex('docs-example'); ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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) } idx, err := pc.DescribeIndex(ctx, "docs-example") if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err) } else { fmt.Printf("index: %v\n", prettifyStruct(idx)) } } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/indexes/docs-example" \ -H "Api-Key: YOUR_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` The response includes the private endpoint URL as the `private_host` value: ```json JavaScript {6} theme={null} { name: 'docs-example', dimension: 1536, metric: 'cosine', host: 'docs-example-jl7boae.svc.aped-4627-b74a.pinecone.io', privateHost: 'docs-example-jl7boae.svc.private.aped-4627-b74a.pinecone.io', deletionProtection: 'disabled', tags: { environment: 'production' }, embed: undefined, spec: { byoc: undefined, pod: undefined, serverless: { cloud: 'aws', region: 'us-east-1' } }, status: { ready: true, state: 'Ready' }, vectorType: 'dense' } ``` ```go Go {5} theme={null} index: { "name": "docs-example", "dimension": 1536, "host": "docs-example-jl7boae.svc.aped-4627-b74a.pinecone.io", "private_host": "docs-example-jl7boae.svc.private.aped-4627-b74a.pinecone.io", "metric": "cosine", "deletion_protection": "disabled", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "tags": { "environment": "production" } } ``` ```json curl {12} theme={null} { "id": "025117b3-e683-423c-b2d1-6d30fbe5027f", "vector_type": "dense", "name": "docs-example", "metric": "cosine", "dimension": 1536, "status": { "ready": true, "state": "Ready" }, "host": "docs-example-jl7boae.svc.aped-4627-b74a.pinecone.io", "private_host": "docs-example-jl7boae.svc.private.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws" } }, "deletion_protection": "disabled", "tags": { "environment": "production" } ``` If you run data operations against an index from outside the Private Endpoint, you will get an `Unauthorized` response. ## Manage internet access to your project Once your Private Endpoint is configured, you can turn off internet access to your project. To enable private endpoint access only: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select your project. 3. Go to **Network > Access**. 4. Turn the **Private endpoint access only** toggle on. This will turn off internet access to the project. This can be turned off at any point. This access control is set at the *project-level* and can unintentionally affect Pinecone indexes that communicate via the internet in the same project. Only indexes communicating through Private Endpoints will continue to work. ## Manage Private Endpoints In addition to [creating Private Endpoints](#2-add-a-private-endpoint-in-pinecone), you can also: * [View Private Endpoints](#view-private-endpoints) * [Delete a Private Endpoint](#delete-a-private-endpoint) ### View Private Endpoints To view Private Endpoints using the [Pinecone console](https://app.pinecone.io/organizations/-/projects): 1. Select your project. 2. Go to **Manage > Network**. A list of Private Endpoints displays with the associated endpoint ID and cloud provider. ### Delete a Private Endpoint To delete a Private Endpoint using the [Pinecone console](https://app.pinecone.io/organizations/-/projects): 1. Select your project. 2. Go to **Manage > Network**. 3. For the Private Endpoint you want to delete, click the *...* (Actions) icon. 4. Click **Delete**. 5. Enter the endpoint name. 6. Click **Delete Endpoint**. # Configure SSO with Okta Source: https://docs.pinecone.io/guides/production/configure-single-sign-on/okta Set up SAML single sign-on between Pinecone and Okta so your organization members can log in with corporate credentials. This page describes how to set up Pinecone with Okta as the single sign-on (SSO) provider. These instructions can be adapted for any provider with SAML 2.0 support. SSO is available on Standard and Enterprise plans. ## Before you begin This page assumes you have the following: * Access to your organization's [Pinecone console](https://login.pinecone.io) as an [organization owner](/guides/organizations/understanding-organizations#organization-roles). * Access to your organization's [Okta Admin console](https://login.okta.com/). ## 1. Start SSO setup in Pinecone First, start setting up SSO in Pinecone. In this step, you'll capture a couple values necessary for configuring Okta in [Step 2](#2-create-an-app-integration-in-okta). 1. In the Pinecone console, go to [**Settings > Access > Identity provider**](https://app.pinecone.io/organizations/-/settings/access/identity-provider). 2. In the **Single sign-on** section, click **Enable SSO**. 3. In the **Setup SSO** dialog, copy the **Entity ID** and the **Assertion Consumer Service (ACS) URL**. You'll need these values in [Step 2](#2-create-an-app-integration-in-okta). 4. Click **Next**. Keep this window or browser tab open. You'll come back to it in [Step 4](#4-complete-sso-setup-in-pinecone). ## 2. Create an app integration in Okta In [Okta](https://login.okta.com/), follow these steps to create and configure a Pinecone app integration: 1. If you're not already on the Okta Admin console, navigate there by clicking the **Admin** button. 2. Navigate to **Applications > Applications**. 3. Click **Create App Integration**. 4. Select **SAML 2.0**. 5. Click **Next**. 6. Enter the **General Settings**: * **App name**: `Pinecone` * **App logo**: (optional) * **App visibility**: Set according to your organization's needs. 7. Click **Next**. 8. For **SAML Settings**, enter values you copied in [Step 1](#1-start-sso-setup-in-pinecone): * **Single sign-on URL**: Your **Assertion Consumer Service (ACS) URL** * **Audience URI (SP Entity ID)**: Your **Entity ID** * **Name ID format**: `EmailAddress` * **Application username**: `Okta username` * **Update application username on**: `Create and update` 9. In the **Attribute Statements (SAML)** section, create the following attribute: * **Name**: `email` * **Value**: `user.email` In newer versions of Okta, attribute statements are configured on the app's **Sign On** tab after the app is created, rather than in the app creation wizard. If you don't see the **Attribute Statements (SAML)** section here, finish creating the app, then add the attribute from **Applications > Pinecone > Sign On**, expanding **Show legacy configuration** if needed. 10. Click **Next**. 11. Click **Finish**. ## 3. Get the sign on URL and certificate from Okta Next, in Okta, get the URL and certificate for the Pinecone application you just created. You'll use these in [Step 4](#4-complete-sso-setup-in-pinecone). 1. In the Okta Admin console, navigate to **Applications > Pinecone > Sign On**. If you're continuing from the previous step, you should already be on the right page. 2. In the **SAML 2.0** section, expand **More details**. 3. Copy the **Sign on URL**. 4. Download the **Signing Certificate**. Download the certificate, don't copy it. The downloaded version contains necessary `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines. ## 4. Complete SSO setup in Pinecone In the browser tab or window you kept open in [Step 1](#1-start-sso-setup-in-pinecone), complete the SSO setup in Pinecone: 1. In the **SSO Setup** window, enter the following values: * **Login URL**: The URL copied in [Step 3](#3-get-the-sign-on-url-and-certificate-from-okta). * **Email domain**: Your company's email domain. To target multiple domains, enter each domain separated by a comma. * **Certificate**: The contents of the certificate file you copied in [Step 3](#3-get-the-sign-on-url-and-certificate-from-okta). When pasting the certificate, be sure to include the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines. 2. Choose whether or not to **Enforce SSO for all users**. * If enabled, all members of your organization must use SSO to log in to Pinecone. * If disabled, members can choose to log in with SSO or with their Pinecone credentials. 3. Click **Next**. 4. Select a **Default role** for all users who log in with SSO. You can change user roles later. The **Default role** does not apply if you enable [SAML role management](/guides/production/configure-single-sign-on/okta-role-management). In that mode, every user's organization and project roles come entirely from your identity provider's SAML attributes. When users first log in via SSO, they receive the default SSO role regardless of their previous role. Subsequent SSO logins do not change the role. If the default is **Member** or **Manager**, existing owners will lose owner access on their first SSO login. To prevent losing access to organization management features: * **Sole owner**: Temporarily set the default to **Owner**, log in via SSO to retain owner access, then change the default back to **Member**. After changing it back, check your organization's user list to verify no one else logged in via SSO while the default was **Owner**—if they did, adjust their roles accordingly. * **Multiple owners**: Keep at least one owner signed in via email while others log in via SSO. That owner can restore roles as needed, then log in via SSO last. If all owners lose access, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Okta is now ready to be used for single sign-on. Follow the [Okta docs](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-main.htm) to learn how to add users and groups. ## Manage roles automatically Optionally, you can have Pinecone assign organization and project roles automatically from your identity provider on each login, instead of managing them manually. For more information, see [Manage roles with Okta](/guides/production/configure-single-sign-on/okta-role-management). # Manage roles with Okta Source: https://docs.pinecone.io/guides/production/configure-single-sign-on/okta-role-management Automatically assign Pinecone organization and project roles from SAML attributes with Okta. Instead of managing roles manually in Pinecone, you can have Pinecone automatically assign organization and project roles from your identity provider (IdP) on each login. This page continues [Configure SSO with Okta](/guides/production/configure-single-sign-on/okta) and shows how to set up SAML role management with Okta. These instructions can be adapted for any provider with SAML 2.0 support. SAML role management is available on the Enterprise plan and builds on SAML SSO. Before you begin, [configure SSO with Okta](/guides/production/configure-single-sign-on/okta) and enforce SSO for your organization. ## How it works When SAML role management is enabled, Pinecone reconciles each user's roles on every SSO login: * Pinecone reads the roles your IdP sends in the SAML `roles` attribute. * It replaces the user's organization and project roles with *exactly* the roles in that attribute. Roles for projects not included in the attribute are removed, and values that don't match a known role are ignored. * Because roles come entirely from your IdP, while this mode is enabled you can no longer invite members or edit roles in the Pinecone console or through the Admin API, and the SSO **Default role** is not applied. * To revoke a member's access, remove their roles in your IdP. At their next sign-in, Pinecone clears all of their organization and project roles and blocks the login. Active members are re-authenticated at least every 24 hours, so the change applies within a day. Because SSO is enforced, deactivating or removing a member in your IdP blocks them from signing in to Pinecone right away, so their access ends immediately. Their role assignments stay in Pinecone until their next sign-in—which a removed member never reaches—so the assignments remain but grant no access on their own. To clear them, or to have Pinecone remove members automatically, use [SCIM provisioning](/guides/production/configure-single-sign-on/okta-scim-provisioning). You can also switch to **Manage roles in Pinecone** to remove the member manually, then switch back. To avoid losing access, configure and verify the `roles` attribute in Okta *before* you enable SAML role management in Pinecone. The steps below are in that order. Enabling SAML role management does not validate your IdP configuration, so a user missing an organization role can be locked out on their next login. Before you enable it, verify the `roles` attribute for a current owner (see [Step 2](#2-verify-the-roles-in-the-saml-assertion)). ## Role attribute values Pinecone reads roles from the `roles` attribute. Each value uses one of the following formats: * Organization role: `pinecone:` * Project role: `pinecone:project::` `` is the project's unique ID. To find it, go to the project list in the [Pinecone console](https://app.pinecone.io/organizations/-/projects). For more information, see [Project IDs](/guides/projects/understanding-projects#project-ids). A user can hold multiple roles by sending multiple values in the `roles` attribute. ### Organization roles For details on what each [organization role](/guides/organizations/understanding-organizations#organization-roles) grants, see [Understanding organizations](/guides/organizations/understanding-organizations#organization-roles). | Organization role | Attribute value | | :------------------- | :------------------------- | | Organization owner | `pinecone:OrgOwner` | | Organization manager | `pinecone:OrgManager` | | Organization member | `pinecone:OrgMember` | | Billing admin | `pinecone:OrgBillingAdmin` | ### Project roles For details on what each [project role](/guides/projects/understanding-projects#project-roles) grants, see [Understanding projects](/guides/projects/understanding-projects#project-roles). | Project role | Attribute value | | :------------------- | :------------------------------------------------ | | Project owner | `pinecone:project::ProjectOwner` | | Project manager | `pinecone:project::ProjectManager` | | Project member | `pinecone:project::ProjectMember` | | Control plane editor | `pinecone:project::ControlPlaneEditor` | | Control plane viewer | `pinecone:project::ControlPlaneViewer` | | Data plane editor | `pinecone:project::DataPlaneEditor` | | Data plane viewer | `pinecone:project::DataPlaneViewer` | For example, to make a user an organization manager who is also a project owner on one project, send these two values in the `roles` attribute: ```text theme={null} pinecone:OrgManager pinecone:project:a2f7dddb-1597-4eff-9f71-535fde243f58:ProjectOwner ``` ## 1. Send roles from Okta Configure Okta to send each user's roles in a SAML attribute named `roles`, where each value is one of the [role attribute values](#role-attribute-values) above. You can populate that attribute in a few ways; choose whichever fits how you already manage users in Okta. In newer versions of Okta, attribute and group statements are configured on the app's **Sign On** tab after the app is created, rather than in the app creation wizard. If you don't see the **Attribute Statements (SAML)** section, expand **Show legacy configuration** within it. ### Option A: From a user profile attribute Use this option to set roles directly on each user's Okta profile. 1. In Okta, go to **Directory > Profile Editor** and edit the **Okta** user profile. 2. Add an attribute named `pineconeRoles` with data type **string array**. 3. For each user, set `pineconeRoles` to their `pinecone:*` values (directly, or through a profile mapping). 4. In **Applications > Pinecone > Sign On**, add an **Attribute Statement**: * **Name**: `roles` * **Name format**: `Unspecified` * **Value**: `user.pineconeRoles` ### Option B: From group membership Use this option to assign roles by adding users to Okta groups. 1. In Okta, create a group for each Pinecone role you want to assign, naming each group exactly as the role's attribute value (for example, `pinecone:OrgOwner` or `pinecone:project::ProjectManager`), and add the appropriate users to each group. 2. In **Applications > Pinecone > Sign On**, send those group names in the `roles` attribute using either: * A **Group Attribute Statement** with **Name** `roles`, **Name format** `Unspecified`, and **Filter** **Starts with** `pinecone:`. * Or an **Attribute Statement** with **Name** `roles` and the expression `user.getGroups({'group.profile.name': 'pinecone:', 'operator': 'STARTS_WITH'}).![profile.name]`. The `user.getGroups(...).![profile.name]` expression is for an app-level attribute statement on the **Sign On** tab, and it returns every matching group, so no `limit` argument is required. (Only the `Groups.startsWith`, `Groups.endsWith`, and `Groups.contains` functions require a `limit`.) If you configure this claim on a custom authorization server instead, use the `.![name]` projection. Any other approach works as well, as long as the `roles` attribute resolves to the role attribute values. ## 2. Verify the roles in the SAML assertion Before you hand role management to Okta, confirm the `roles` attribute contains what you expect. 1. In **Applications > Pinecone > Sign On**, click **Preview the SAML Assertion**. 2. Select a user who should be an organization owner and generate the preview. 3. Confirm the assertion includes a `roles` attribute containing `pinecone:OrgOwner` (and any project roles you assigned). If no current organization owner's preview includes `pinecone:OrgOwner`, fix your Okta configuration before continuing. Enabling SAML role management without a provisioned owner can lock your organization out of role management. If the `roles` attribute is empty or missing, re-check your attribute statement expression and projection before continuing, as a malformed expression returns no roles rather than an error. ## 3. Enable SAML role management in Pinecone You must be an [organization owner](/guides/organizations/understanding-organizations#organization-roles) on the Enterprise plan, and SSO must be enforced for your organization. 1. In the Pinecone console, go to [**Settings > Access > Identity provider**](https://app.pinecone.io/organizations/-/settings/access/identity-provider). 2. Confirm that single sign-on shows the **Enforced** status. If it does not, edit your SSO configuration to enforce SSO before continuing. 3. In the **User management** section, select **Manage roles with SAML attributes**. 4. In the **Enable SAML role management** dialog, review the **Before you enable** prerequisites, then click **Enable SAML role management**. Role assignment now comes entirely from your IdP. Roles update at the member's next SSO login. Since SAML sessions re-authenticate at least every 24 hours, an active user's role changes apply within 24 hours. Default role assignments configured during SSO setup no longer apply. To stop syncing roles from your IdP, return to **Settings > Access > Identity provider** and select **Manage roles in Pinecone**. Existing roles are preserved, and you can edit them again in the console. # SCIM provisioning with Okta Source: https://docs.pinecone.io/guides/production/configure-single-sign-on/okta-scim-provisioning Automatically provision members and roles from Okta to Pinecone over SCIM. Instead of managing members and roles manually in Pinecone, you can have your identity provider (IdP) provision them automatically over SCIM. This page continues [Configure SSO with Okta](/guides/production/configure-single-sign-on/okta) and shows how to set up SCIM provisioning with Okta. These instructions can be adapted for any provider with SCIM 2.0 support. SCIM provisioning is available on the Enterprise plan and builds on SAML SSO. Before you begin, [configure SSO with Okta](/guides/production/configure-single-sign-on/okta) and enforce SSO for your organization. ## How it works When SCIM provisioning is enabled, your IdP manages organization membership and roles in Pinecone in near real time: * As members are added, updated, or removed in Okta, those changes sync to Pinecone over SCIM in near real time, not just at login. * Okta connects to a SCIM endpoint that Pinecone provides, authenticating with a bearer token you generate in the Pinecone console. * Pinecone reads each member's roles from the SCIM `roles` attribute and sets their organization and project roles to *exactly* those values. Values that don't match a known role are ignored. * While SCIM is enabled, SCIM is the source of truth for roles: Pinecone no longer applies the roles in a member's SAML login assertion, even though members still sign in through SAML SSO. * Deactivating or removing a member in Okta removes them from the organization, and clearing a member's roles revokes their access. * Because membership and roles come entirely from your IdP, while SCIM is enabled you can no longer invite members or edit roles in the Pinecone console or through the Admin API. Provisioning changes in Okta are typically reflected in Pinecone within a few minutes, but can take up to 30 minutes to fully propagate. SCIM provisioning assigns roles from user attributes only. SCIM group push is not supported. This is similar to [SAML role management](/guides/production/configure-single-sign-on/okta-role-management), except roles are provisioned continuously rather than at each login, and member deprovisioning is handled automatically. Before you enable SCIM, provision at least one current [organization owner](/guides/organizations/understanding-organizations#organization-roles) with the `pinecone:OrgOwner` role. Pinecone blocks enabling SCIM until a current owner has been provisioned as an owner, so that handing role management to your IdP cannot lock you out. SCIM provisioning is not compatible with members who belong to more than one SSO-connected Pinecone organization. If a member is part of multiple SSO-connected organizations, do not provision them through SCIM; manage their roles manually instead. ## Role attribute values Pinecone reads roles from the `roles` attribute. Each value uses one of the following formats: * Organization role: `pinecone:` * Project role: `pinecone:project::` `` is the project's unique ID. To find it, go to the project list in the [Pinecone console](https://app.pinecone.io/organizations/-/projects). For more information, see [Project IDs](/guides/projects/understanding-projects#project-ids). A user can hold multiple roles by sending multiple values in the `roles` attribute. ### Organization roles For details on what each [organization role](/guides/organizations/understanding-organizations#organization-roles) grants, see [Understanding organizations](/guides/organizations/understanding-organizations#organization-roles). | Organization role | Attribute value | | :------------------- | :------------------------- | | Organization owner | `pinecone:OrgOwner` | | Organization manager | `pinecone:OrgManager` | | Organization member | `pinecone:OrgMember` | | Billing admin | `pinecone:OrgBillingAdmin` | ### Project roles For details on what each [project role](/guides/projects/understanding-projects#project-roles) grants, see [Understanding projects](/guides/projects/understanding-projects#project-roles). | Project role | Attribute value | | :------------------- | :------------------------------------------------ | | Project owner | `pinecone:project::ProjectOwner` | | Project manager | `pinecone:project::ProjectManager` | | Project member | `pinecone:project::ProjectMember` | | Control plane editor | `pinecone:project::ControlPlaneEditor` | | Control plane viewer | `pinecone:project::ControlPlaneViewer` | | Data plane editor | `pinecone:project::DataPlaneEditor` | | Data plane viewer | `pinecone:project::DataPlaneViewer` | For example, to make a user an organization manager who is also a project owner on one project, send these two values in the `roles` attribute: ```text theme={null} pinecone:OrgManager pinecone:project:a2f7dddb-1597-4eff-9f71-535fde243f58:ProjectOwner ``` ## 1. Start SCIM setup in Pinecone You must be an [organization owner](/guides/organizations/understanding-organizations#organization-roles) on the Enterprise plan, and SSO must be enforced for your organization. 1. In the Pinecone console, go to [**Settings > Access > Identity provider**](https://app.pinecone.io/organizations/-/settings/access/identity-provider). 2. Confirm that single sign-on shows the **Enforced** status. If it does not, edit your SSO configuration to enforce SSO before continuing. 3. In the **User management** section, select **Manage roles with SCIM provisioning**. 4. In the **Set up SCIM provisioning** dialog, review the instructions and click **Get started**. ## 2. Generate a SCIM token 1. Choose the token's permissions and expiry. By default the token grants all user permissions and expires in 90 days; you can also choose **Token never expires**. 2. Click **Generate token**. 3. Copy the **bearer token**. The **SCIM endpoint** is shown on the next screen of the dialog. You'll add both to Okta in [Step 3](#3-connect-okta-to-the-scim-endpoint). The bearer token is shown only once. Copy it before closing the dialog. You can have at most two active tokens per organization; rotate or revoke them later from the **Manage** dialog. ## 3. Connect Okta to the SCIM endpoint 1. In [Okta](https://login.okta.com/), navigate to **Applications > Pinecone > General**. 2. In the **App Settings** section, click **Edit**, set **Provisioning** to **SCIM**, and click **Save**. 3. Open the **Provisioning** tab and click **Configure API Integration**. 4. Select **Enable API Integration** and enter the following: * **SCIM connector base URL**: The **SCIM endpoint** you copied in [Step 2](#2-generate-a-scim-token). * **Unique identifier field for users**: `userName`. * **Authentication Mode**: `HTTP Header`. * **Authorization**: The **bearer token** you copied in [Step 2](#2-generate-a-scim-token). 5. Click **Test API Credentials** to verify the connection, then click **Save**. 6. Under **Provisioning > To App**, click **Edit** and enable **Create Users**, **Update User Attributes**, and **Deactivate Users**. If the **Provisioning** tab or **Configure API Integration** button does not appear, SCIM provisioning is not enabled on the app. If **Test API Credentials** fails, re-copy the SCIM endpoint and bearer token from Pinecone, and confirm the token has not expired or been revoked. ## 4. Send role values to Pinecone Okta does not send a member's Pinecone roles by default. You define one app attribute per role you want to assign, then map a value to it for the right members. Pinecone reads only each value, so the same approach scales to as many roles as you need. 1. In Okta, go to **Directory > Profile Editor** and open the **Pinecone** app profile. 2. For each role you want to assign, click **Add Attribute** and configure: * **Data type**: `string` * **External name**: `roles.^[type==' ### Private Endpoints Use [Private Endpoints](/guides/production/configure-private-endpoints) to connect via AWS PrivateLink or Azure Private Link. This establishes private connectivity between your Pinecone serverless indexes and your cloud VPC/VNet while keeping traffic off the public internet. PrivateLink diagram Private Endpoints are additive to other Pinecone security features: data is also [encrypted in transit](#encryption-in-transit), [encrypted at rest](#encryption-at-rest), and an [API key](#api-keys) is required to authenticate. ### Proxies The following Pinecone SDKs support the use of proxies: * [Python SDK](/reference/sdks/python/overview#proxy-configuration) * [Node.js SDK](/reference/sdks/node/overview#proxy-configuration) # Create a project Source: https://docs.pinecone.io/guides/projects/create-a-project Create a new Pinecone project in your organization using the console or Admin API, including project name, tags, and customer-managed encryption keys (CMEK). This page shows you how to create a project. If you are an [organization owner or organization manager](/guides/organizations/understanding-organizations#organization-roles), you can create a project in your organization: 1. In the Pinecone console, go to [**your profile > Organization settings > Projects**](https://app.pinecone.io/organizations/-/settings/projects). 2. Click **+ Create Project**. 3. Enter a **Name**. A project name can contain up to 512 characters. For more information, see [Object identifiers](/reference/api/database-limits#identifier-limits). 4. (Optional) Tags are key-value pairs that you can use to categorize and identify the project. To add a tag, click **+ Add tag** and enter a tag key and value. 5. (Optional) Select **Encrypt with Customer Managed Encryption Key**. For more information, see [Configure CMEK](/guides/production/configure-cmek). 6. Click **Create project**. To load an index with a [sample dataset](/guides/data/use-sample-datasets), click **Load sample data** and follow the prompts. The number of projects per organization varies by plan—see [Projects per organization](/reference/api/database-limits#projects-per-organization). To create additional projects, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). An [access token](/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl "https://api.pinecone.io/admin/projects" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -d '{ "name":"example-project" }' ``` ```bash CLI theme={null} # Target the organization for which you want to # create a project. pc target -o "example-org" # Create the project and set it as the target # project for the CLI. pc project create -n "example-project" --target ``` The example returns a response like the following: ```json curl theme={null} { "id": "32c8235a-5220-4a80-a9f1-69c24109e6f2", "name": "example-project", "max_pods": 0, "force_encryption_with_cmek": false, "organization_id": "-NM7af6f234168c4e44a", "created_at": "2025-03-16T22:46:45.030Z" } ``` ```text CLI theme={null} [SUCCESS] Project example-cli-project created successfully. ATTRIBUTE VALUE Name example-project ID 32c8235a-5220-4a80-a9f1-69c24109e6f2 Organization ID -NM7af6f234168c4e44a Created At 2025-10-27 23:27:46.370088 +0000 UTC Force Encryption false Max Pods 5 [SUCCESS] Target project set to example-cli-project ``` ## Next steps * [Add users to your project](/guides/projects/manage-project-members#add-members-to-a-project) * [Create an index](/guides/index-data/create-an-index) # Manage API keys Source: https://docs.pinecone.io/guides/projects/manage-api-keys Create, view, update, and delete Pinecone API keys with custom permissions per project, including scoped roles and data plane access controls. Each Pinecone [project](/guides/projects/understanding-projects) has one or more API keys. In order to [make calls to the Pinecone API](/guides/get-started/quickstart), you must provide a valid API key for the relevant Pinecone project. This page shows you how to [create](#create-an-api-key), [view](#view-project-api-keys), [update](#update-an-api-key), and [delete](#delete-an-api-key) API keys. If you use custom API key permissions, ensure that you [target your index by host](/guides/manage-data/target-an-index#target-by-index-host-recommended) when performing data operations such as `upsert` and `query`. ## Create an API key You can create a new API key for your project, as follows: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select your project. 3. Go to **API keys**. 4. Click **Create API key**. 5. Enter an **API key name**. 6. Select the **Permissions** to grant to the API key. For a description of the permission roles, see [Project roles](/guides/projects/understanding-projects#project-roles). Users on the Starter and Builder plans can set the permissions to **All** only. To customize the permissions further, [upgrade to the Standard or Enterprise plan](/guides/organizations/manage-billing/upgrade-billing-plan). 7. Click **Create key**. 8. Copy and save the generated API key in a secure place for future use. You will not be able to see the API key again after you close the dialog. 9. Click **Close**. An [access token](/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. ```bash curl theme={null} PINECONE_PROJECT_ID="YOUR_PROJECT_ID" PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl -X POST "https://api.pinecone.io/admin/projects/$PINECONE_PROJECT_ID/api-keys" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -d '{ "name": "example-api-key", "roles": ["ProjectEditor"] }' ``` ```bash CLI theme={null} # Target the project for which you want to create an API key. pc target -o "example-org" -p "example-project" # Create the API key pc api-key create -n "example-api-key" --roles ProjectEditor ``` The example returns a response like the following: ```json curl theme={null} { "key": { "id": "62b0dbfe-3489-4b79-b850-34d911527c88", "name": "example-api-key", "project_id": "32c8235a-5220-4a80-a9f1-69c24109e6f2", "roles": [ "ProjectEditor" ], "created_at": "2025-10-20T23:40:27.069075Z" }, "value": "..." } ``` ```text CLI theme={null} ATTRIBUTE VALUE Name example-api-key ID 62b0dbfe-3489-4b79-b850-34d911527c88 Value ... Project ID 32c8235a-5220-4a80-a9f1-69c24109e6f2 Roles ProjectEditor ``` ## View project API keys You can [view the API keys](/reference/api/latest/admin/list_api_keys) for your project: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select your project. 3. Go to the **API keys** tab. You will see a list of all API keys for the project, including their names, IDs, and permissions. An [access token](/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. ```bash curl theme={null} PINECONE_PROJECT_ID="32c8235a-5220-4a80-a9f1-69c24109e6f2" PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl -X GET "https://api.pinecone.io/admin/projects/$PINECONE_PROJECT_ID/api-keys" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ```bash CLI theme={null} PINECONE_PROJECT_ID="32c8235a-5220-4a80-a9f1-69c24109e6f2" pc api-key list -i $PINECONE_PROJECT_ID ``` The example returns a response like the following: ```json curl theme={null} { "data": [ { "id": "62b0dbfe-3489-4b79-b850-34d911527c88", "name": "example-api-key", "project_id": "32c8235a-5220-4a80-a9f1-69c24109e6f2", "roles": [ "ProjectEditor" ], "created_at": "2025-10-20T23:39:43.665754Z" }, { "id": "0d0d3678-81b4-4e0d-a4f0-70ba488acfb7", "name": "example-api-key-2", "project_id": "32c8235a-5220-4a80-a9f1-69c24109e6f2", "roles": [ "ProjectEditor" ], "created_at": "2025-10-20T23:43:13.176422Z" } ] } ``` ```text CLI theme={null} Organization: example-organization (ID: -NM7af6f234168c4e44a) Project: example-project (ID: 32c8235a-5220-4a80-a9f1-69c24109e6f2) API Keys NAME ID PROJECT ID ROLES example-api-key 62b0dbfe-3489-4b79-b850-34d911527c88 32c8235a-5220-4a80-a9f1-69c24109e6f2 ProjectEditor example-api-key-2 0d0d3678-81b4-4e0d-a4f0-70ba488acfb7 32c8235a-5220-4a80-a9f1-69c24109e6f2 ProjectEditor ``` ## View API key details You can [view the details of an API key](/reference/api/latest/admin/fetch_api_key): 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select your project. 3. Go to the **API keys** tab. 4. In the row of the API key you want to change, in the **Actions** column, click **ellipsis (...) menu > Settings**. You will see the API key's name, ID, and permissions. An [access token](/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. ```bash curl theme={null} PINECONE_API_KEY_ID="62b0dbfe-3489-4b79-b850-34d911527c88" PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl -X GET "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "accept: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ```bash CLI theme={null} PINECONE_API_KEY_ID="62b0dbfe-3489-4b79-b850-34d911527c88" pc api-key describe -i $PINECONE_API_KEY_ID ``` The example returns a response like the following: ```json curl theme={null} { "id": "62b0dbfe-3489-4b79-b850-34d911527c88", "name": "example-api-key", "project_id": "32c8235a-5220-4a80-a9f1-69c24109e6f2", "roles": [ "ProjectEditor" ], "created_at": "2025-10-22T19:27:21.202955Z" } ``` ```text CLI theme={null} ATTRIBUTE VALUE Name example-api-key ID 62b0dbfe-3489-4b79-b850-34d911527c88 Project ID 32c8235a-5220-4a80-a9f1-69c24109e6f2 Roles ProjectEditor ``` ## Update an API key Users on the Starter and Builder plans cannot change API key permissions once they are set. Instead, [create a new API key](#create-an-api-key) or [upgrade to the Standard or Enterprise plan](/guides/organizations/manage-billing/upgrade-billing-plan). If you are a [project owner](/guides/projects/understanding-projects#project-roles), you can update the name and roles of an API key: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select your project. 3. Go to the **API keys** tab. 4. In the row of the API key you want to change, in the **Actions** column, click **ellipsis (...) menu > Settings**. 5. Change the name and/or permissions for the API key as needed. For information about the different API key permissions, refer to [Project roles](/guides/projects/understanding-projects#project-roles). 6. Click **Update**. An [access token](/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. ```bash curl theme={null} PINECONE_API_KEY_ID="62b0dbfe-3489-4b79-b850-34d911527c88" PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl -X PATCH "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -d '{ "name": "new-api-key-name", "roles": ["ProjectEditor"] }' ``` ```bash CLI theme={null} PINECONE_API_KEY_ID="62b0dbfe-3489-4b79-b850-34d911527c88" # Target the organization that contains the API key. pc target -o "example-org" # Update the API key name. pc api-key update -i $PINECONE_API_KEY_ID -n "new-api-key-name" ``` The example returns a response like the following: ```json curl theme={null} { "id": "62b0dbfe-3489-4b79-b850-34d911527c88", "name": "new-api-key-name", "project_id": "32c8235a-5220-4a80-a9f1-69c24109e6f2", "roles": [ "ProjectEditor" ], "created_at": "2025-10-22T19:27:21.202955Z" } ``` ```text CLI theme={null} ATTRIBUTE VALUE Name new-api-key-name ID 62b0dbfe-3489-4b79-b850-34d911527c88 Project ID 32c8235a-5220-4a80-a9f1-69c24109e6f2 Roles ProjectEditor ``` ## Delete an API key If you are a [project owner](/guides/projects/understanding-projects#project-roles), you can delete your API key: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select your project. 3. Go to the **API keys** tab. 4. In the row of the API key you want to change, in the **Actions** column, click **ellipsis (...) menu > Delete**. 5. Enter the **API key name**. 6. Click **Confirm deletion**. Deleting an API key is irreversible and will immediately disable any applications using the API key. An [access token](/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. ```bash curl theme={null} PINECONE_API_KEY_ID="62b0dbfe-3489-4b79-b850-34d911527c88" PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl -X DELETE "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" ``` ```bash CLI theme={null} PINECONE_API_KEY_ID="62b0dbfe-3489-4b79-b850-34d911527c88" # Delete the API key. Use --skip-confirmation to skip # the confirmation prompt. pc api-key delete -i $PINECONE_API_KEY_ID ``` The example returns a response like the following: ```text curl theme={null} No response payload ``` ```text CLI theme={null} [WARN] This operation will delete API key example-api-key from project example-project. [WARN] Any integrations that authenticate with this API key will immediately stop working. [WARN] This action cannot be undone. Do you want to continue? (y/N): y [INFO] You chose to continue delete. [SUCCESS] API key example-api-key deleted ``` # Manage project members Source: https://docs.pinecone.io/guides/projects/manage-project-members Add, remove, and update Pinecone project members using role-based access control (RBAC) to manage permissions and project owner roles. [Organization owners](/guides/organizations/understanding-organizations#organization-roles) or [project owners](/guides/projects/understanding-projects#project-roles) can manage members in a project. Each member is assigned one or more [project roles](/guides/projects/understanding-projects#project-roles) that determine their permissions within the project. To assign and manage roles programmatically with the Admin API, or to manage roles for service accounts and API keys, see [Manage roles and access](/guides/production/manage-rbac). For information about managing members at the **organization-level**, see [Manage organization members](/guides/organizations/manage-organization-members). ## Add members to a project Project owners can add existing organization members to a project and manage their project roles. Only [organization owners](/guides/organizations/understanding-organizations#organization-roles) can invite people who are not yet members of the organization. You can add members to a project in the [Pinecone console](https://app.pinecone.io/organizations/-/projects): 1. Select your project. 2. Go to the [**Manage > Access > Members** tab](https://app.pinecone.io/organizations/-/projects/-/access/members). 3. Enter the member's email address or name. 4. Select a [**Project role**](/guides/projects/understanding-projects#project-roles) for the member. The role determines the member's permissions within Pinecone. 5. Click **Invite**. When you invite a member to join your project, Pinecone sends them an email containing a link that enables them to gain access to the project. If they already have a Pinecone account, they still receive an email, but they can also immediately view the project. ## Change a member's role You can change a member's role in the [Pinecone console](https://app.pinecone.io/organizations/-/projects): 1. Select your project. 2. Go to the [**Manage > Access > Members** tab](https://app.pinecone.io/organizations/-/projects/-/access/members). 3. In the row of the member you want to edit, click **ellipsis (...) menu > Edit role**. 4. Select a [**Project role**](/guides/projects/understanding-projects#project-roles) for the member. 5. Click **Edit role**. ## Remove a member You can remove a member from a project in the [Pinecone console](https://app.pinecone.io/organizations/-/projects): 1. Select your project. 2. Go to the [**Manage > Access > Members** tab](https://app.pinecone.io/organizations/-/projects/-/access/members). 3. In the row of the member you want to remove, click **ellipsis (...) menu > Remove member**. 4. Click **Remove member**. To remove yourself from a project, click the **Leave project** button in your user's row and confirm. # Manage projects Source: https://docs.pinecone.io/guides/projects/manage-projects View project details, rename projects, and delete projects in your Pinecone organization using the console or Admin API with owner permissions. This page shows you how to view project details, rename a project, and delete a project. You must be an [organization owner](/guides/organizations/understanding-organizations#organization-roles) or [project owner](/guides/projects/understanding-projects#project-roles) to edit project details or delete a project. ## View project details You can view the details of a project, as in the following example: An [access token](/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PROJECT_ID="32c8235a-5220-4a80-a9f1-69c24109e6f2" curl -X GET "https://api.pinecone.io/admin/projects/$PROJECT_ID" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "accept: application/json" ``` ```bash CLI theme={null} PROJECT_ID="32c8235a-5220-4a80-a9f1-69c24109e6f2" # Target the organization that contains the project. pc target -o "example-org" # Fetch the project details. pc project describe -i $PROJECT_ID ``` The example returns a response like the following: ```json curl theme={null} { "id": "32c8235a-5220-4a80-a9f1-69c24109e6f2", "name": "example-project", "max_pods": 5, "force_encryption_with_cmek": false, "organization_id": "-NM7af6f234168c4e44a", "created_at": "2025-10-27T23:27:46.370088Z" } ``` ```text CLI theme={null} ATTRIBUTE VALUE Name example-project ID 32c8235a-5220-4a80-a9f1-69c24109e6f2 Organization ID -NM7af6f234168c4e44a Created At 2025-10-27 23:27:46.370088 +0000 UTC Force Encryption false Max Pods 5 ``` You can view project details using the [Pinecone console](https://app.pinecone.io/organizations/-/settings/projects/-/indexes). ## Rename a project You can change the name of your project: 1. In the Pinecone console, go to [**Settings > Projects**](https://app.pinecone.io/organizations/-/settings/projects). 2. Click the **ellipsis (...) menu > Configure** icon next to the project you want to update. 3. Enter a new **Project Name**. A project name can contain up to 512 characters. 4. Click **Save Changes**. An [access token](/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. ```bash curl theme={null} PROJECT_ID="YOUR_PROJECT_ID" PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl -X PATCH "https://api.pinecone.io/admin/projects/$PROJECT_ID" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "updated-example-project" }' ``` ```bash CLI theme={null} PROJECT_ID="YOUR_PROJECT_ID" # Target the project to update. pc target -o "example-org" "example-project" # Update the project name. pc project update -i $PROJECT_ID -n "updated-example-project" ``` The example returns a response like the following: ```json curl theme={null} { "id": "32c8235a-5220-4a80-a9f1-69c24109e6f2", "name": "updated-example-project", "max_pods": 5, "force_encryption_with_cmek": false, "organization_id": "-NM7af6f234168c4e44a", "created_at": "2025-10-27T23:27:46.370088Z" } ``` ```text CLI theme={null} [SUCCESS] Project 32c8235a-5220-4a80-a9f1-69c24109e6f2 updated successfully. ATTRIBUTE VALUE Name updated-example-project ID 32c8235a-5220-4a80-a9f1-69c24109e6f2 Organization ID -NM7af6f234168c4e44a Created At 2025-10-27 23:27:46.370088 +0000 UTC Force Encryption false Max Pods 5 ``` ## Add project tags Project tags are key-value pairs that you can use to categorize and identify a project. To add project tags, use the Pinecone console. 1. In the Pinecone console, go to [**Settings > Projects**](https://app.pinecone.io/organizations/-/settings/projects). 2. Click the **ellipsis (...) menu > Configure** icon next to the project you want to update. 3. Click **+ Add tag** and enter a tag key and value. Repeat for each tag you want to add. 4. Click **Save Changes**. You can also [add tags to indexes](/guides/manage-data/manage-indexes#configure-index-tags). ## Delete a project To delete a project, you must first [delete all data](/guides/manage-data/delete-data), [indexes](/guides/manage-data/manage-indexes#delete-an-index), [collections](/guides/indexes/pods/back-up-a-pod-based-index#delete-a-collection), [backups](/guides/manage-data/back-up-an-index#delete-a-backup) and [assistants](/guides/assistant/manage-assistants#delete-an-assistant) associated with the project. Then, you can delete the project itself: 1. In the Pinecone console, go to [**Settings > Projects**](https://app.pinecone.io/organizations/-/settings/projects). 2. For the project you want to delete, click the **ellipsis (...) menu > Delete**. 3. Enter the project name to confirm the deletion. 4. Click **Delete Project**. An [access token](/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PROJECT_ID="32c8235a-5220-4a80-a9f1-69c24109e6f2" curl -X DELETE "https://api.pinecone.io/admin/projects/$PROJECT_ID" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" ``` ```bash CLI theme={null} PINECONE_PROJECT_ID="32c8235a-5220-4a80-a9f1-69c24109e6f2" # Target the organization that contains the project. pc target -o "example-org" # Delete the project. Use --skip-confirmation to skip # the confirmation prompt. pc project delete -i $PINECONE_PROJECT_ID ``` # Manage service accounts at the project-level Source: https://docs.pinecone.io/guides/projects/manage-service-accounts Add service accounts to a Pinecone project and assign project roles to enable programmatic API access for automated workflows and CI pipelines. This feature is in [public preview](/release-notes/feature-availability) and available only on [Enterprise plans](https://www.pinecone.io/pricing/). This page shows how [organization owners](/guides/organizations/understanding-organizations#organization-roles) and [project owners](/guides/projects/understanding-projects#project-roles) can add and manage service accounts at the project-level. Service accounts enable programmatic access to Pinecone's Admin API, which can be used to create and manage projects and API keys. ## Add a service account to a project After a service account has been [added to an organization](/guides/organizations/manage-service-accounts#create-a-service-account), it can be added to a project in the [Pinecone console](https://app.pinecone.io/organizations/-/projects): 1. Select your project. 2. Go to the [**Manage > Access > Service accounts** tab](https://app.pinecone.io/organizations/-/projects/-/access/service-accounts). 3. Select the service account to add. 4. Select a [**Project role**](/guides/projects/understanding-projects#project-roles) for the service account. The role determines its permissions within Pinecone. 5. Click **Connect**. ## Change project role To change a service account's role in the [Pinecone console](https://app.pinecone.io/organizations/-/projects): 1. Select your project. 2. Go to the [**Manage > Access > Service accounts** tab](https://app.pinecone.io/organizations/-/projects/-/access/service-accounts). 3. In the row of the service account you want to edit, click **ellipsis (...) menu > Edit role**. 4. Select a [**Project role**](/guides/projects/understanding-projects#project-roles) for the service account. 5. Click **Edit role**. ## Remove a service account from a project To remove a service account from a project in the [Pinecone console](https://app.pinecone.io/organizations/-/projects): 1. Select your project. 2. Go to the [**Manage > Access > Service accounts** tab](https://app.pinecone.io/organizations/-/projects/-/access/service-accounts). 3. In the row of the service account you want to remove, click **ellipsis (...) menu > Disconnect**. 4. Enter the service account name to confirm. 5. Click **Disconnect**. # Understanding projects Source: https://docs.pinecone.io/guides/projects/understanding-projects Learn how Pinecone projects organize indexes, cloud environments, API keys, and members, including project roles and per-role permission summaries. A Pinecone project belongs to an [organization](/guides/organizations/understanding-organizations) and contains a number of [indexes](/guides/index-data/indexing-overview) and users. Only a user who belongs to the project can access the indexes in that project. Each project also has at least one project owner. ## Project environments You choose a cloud environment for each index in a project. This makes it easy to manage related resources across environments and use the same API key to access them. ## Project roles If you are an [organization owner](/guides/organizations/understanding-organizations#organization-roles) or project owner, you can manage who has access to a project. You grant a principal—a user, [service account](/guides/projects/manage-service-accounts), or [API key](/guides/projects/manage-api-keys)—access by assigning it one or more roles scoped to the project. A principal can hold more than one role, and its effective permissions are the union of all the roles it holds. The roles you assign depend on the principal type: * **Users and service accounts** are typically assigned a membership role—`ProjectOwner`, `ProjectManager`, or `ProjectMember`—optionally combined with one or more access roles. * **API keys** are typically assigned `ProjectEditor` or `ProjectViewer`, or one or more access roles. API keys cannot be assigned `ProjectOwner`, `ProjectManager`, or `ProjectMember`, which include access to project settings, members, and API keys. To access these items programmatically, use a [service account](/guides/projects/manage-service-accounts). The following project roles are available: | Role | Permissions | | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------ | | Project owner (`ProjectOwner`) | Full access to the project, including members, API keys, and all resources and data. | | Project manager (`ProjectManager`) | Read and write access to all resources and data. Read-only access to project settings, members, and API keys. | | Project member (`ProjectMember`) | Read-only access to project settings, members, and API keys. No resource or data access unless granted additional access roles. | | Project editor (`ProjectEditor`) | Read and write access to all resources and data. No access to project settings, members, or API keys. | | Project viewer (`ProjectViewer`) | Read-only access to all resources and data. No access to project settings, members, or API keys. | | Control plane editor (`ControlPlaneEditor`) | Read and write access to control plane resources, such as indexes, assistants, backups, and collections. | | Control plane viewer (`ControlPlaneViewer`) | Read-only access to control plane resources. | | Data plane editor (`DataPlaneEditor`) | Read and write access to data plane data, such as records, namespaces, and assistant files. | | Data plane viewer (`DataPlaneViewer`) | Read-only access to data plane data. | The following table details the project settings, resource, and data permissions for the owner, manager, and member roles: | Permission | Owner | Manager | Member | | :-------------------------------------------------------------------------- | :---: | :-----: | :----: | | View project settings, members, and API keys | ✓ | ✓ | ✓ | | Update project settings and configuration | ✓ | | | | Delete the project | ✓ | | | | Manage project members and their roles | ✓ | | | | Create and delete API keys | ✓ | | | | View indexes, assistants, backups, and collections | ✓ | ✓ | | | Create, configure, and delete indexes, assistants, backups, and collections | ✓ | ✓ | | | Read index data (query, fetch, list, and view stats) | ✓ | ✓ | | | Write index data (upsert, update, delete, and import) | ✓ | ✓ | | Specific to pod-based indexes: Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates). | Permission | Owner | Manager | Member | | :------------------------ | :---: | :-----: | :----: | | View project pod limits | ✓ | ✓ | ✓ | | Update project pod limits | ✓ | | | | Update index size | ✓ | ✓ | | Pod-based indexes do not support role-based access control and will always grant data plane read and write access to project members. ### Role permissions The following tables detail the operations covered by the general, control plane, and data plane roles: #### General permissions | Role | Permissions | | :-------------- | :---------------------------------------------- | | `ProjectEditor` | Permissions to read and write all project data. | | `ProjectViewer` | Permissions to read all project data. | #### Control plane permissions | Role | Permissions | | :------------------- | :---------------------------------------------------------------------------------------------------------- | | `ControlPlaneEditor` | Permissions to list, describe, create, delete, and configure indexes, backups, collections, and assistants. | | `ControlPlaneViewer` | Permissions to list and describe indexes, backups, collections, and assistants. | | None | No control plane permissions. | #### Data plane permissions | Role | Permissions | | :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DataPlaneEditor` |
  • Indexes: Permissions to query, import, fetch, add, update, and delete index data.
  • Pinecone Assistant: Permissions to add, list, view, and delete files; chat with an assistant, and evaluate responses.
  • Pinecone Inference: Permissions to generate embeddings and rerank documents.
| | `DataPlaneViewer` |
  • Indexes: Permissions to query, fetch, list ID, and view stats.
  • Pinecone Assistant: Permissions to list and view files, chat with an assistant, and evaluate responses.
  • Pinecone Inference: Permissions to generate embeddings and rerank documents.
| | None | No data plane permissions. | ## API keys Each Pinecone [project](/guides/projects/understanding-projects) has one or more API keys. In order to [make calls to the Pinecone API](/guides/get-started/quickstart), you must provide a valid API key for the relevant Pinecone project. For more information, see [Manage API keys](/guides/projects/manage-api-keys). ## Project IDs Each Pinecone project has a unique project ID. To find the ID of a project, go to the project list in the [Pinecone console](https://app.pinecone.io/organizations/-/projects). ## See also * [Understanding organizations](/guides/organizations/understanding-organizations) * [Manage organization members](/guides/organizations/manage-organization-members) # Filter by metadata Source: https://docs.pinecone.io/guides/search/filter-by-metadata Narrow Pinecone search results by adding metadata filter expressions to your query, using operators like $eq, $in, $gt, and $and for precise retrieval. Every [record](/guides/get-started/concepts#record) in an index must contain an ID and a dense or sparse vector. In addition, you can include [metadata key-value pairs](/guides/index-data/indexing-overview#metadata) to store related information or context. When you search the index, you can then include a metadata filter to limit the search to records matching the filter expression. ## Search with a metadata filter The following code searches for the 3 records that are most semantically similar to a query and that have a `category` metadata field with the value `digestive system`. Searching with text is supported only for [indexes with integrated embedding](/guides/index-data/indexing-overview#integrated-embedding). ```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/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") filtered_results = index.search( namespace="example-namespace", query={ "inputs": {"text": "Disease prevention"}, "top_k": 3, "filter": {"category": "digestive system"}, }, fields=["category", "chunk_text"] ) print(filtered_results) ``` ```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/manage-data/target-an-index const namespace = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace"); const response = await namespace.searchRecords({ query: { topK: 3, inputs: { text: "Disease prevention" }, filter: { category: "digestive system" } }, fields: ['chunk_text', 'category'] }); console.log(response); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import org.openapitools.db_data.client.ApiException; import org.openapitools.db_data.client.model.SearchRecordsResponse; import java.util.*; public class SearchText { public static void main(String[] args) throws ApiException { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "integrated-dense-java"); String query = "Disease prevention"; List fields = new ArrayList<>(); fields.add("category"); fields.add("chunk_text"); Map filter = new HashMap<>(); filter.put("category", "digestive system"); // Search the index SearchRecordsResponse recordsResponse = index.searchRecordsByText(query, "example-namespace", fields, 3, filter, null); // Print the results System.out.println(recordsResponse); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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/manage-data/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) } metadataMap := map[string]interface{}{ "category": map[string]interface{}{ "$eq": "digestive system", }, } res, err := idxConnection.SearchRecords(ctx, &pinecone.SearchRecordsRequest{ Query: pinecone.SearchRecordsQuery{ TopK: 3, Inputs: &map[string]interface{}{ "text": "Disease prevention", }, Filter: &metadataMap, }, Fields: &[]string{"chunk_text", "category"}, }) if err != nil { log.Fatalf("Failed to search records: %v", err) } fmt.Printf(prettifyStruct(res)) } ``` ```shell curl theme={null} INDEX_HOST="INDEX_HOST" NAMESPACE="YOUR_NAMESPACE" PINECONE_API_KEY="YOUR_API_KEY" curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: unstable" \ -d '{ "query": { "inputs": {"text": "Disease prevention"}, "top_k": 3, "filter": {"category": "digestive system"} }, "fields": ["category", "chunk_text"] }' ``` ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.query( namespace="example-namespace", vector=[0.0236663818359375,-0.032989501953125, ..., -0.01041412353515625,0.0086669921875], top_k=3, filter={ "category": {"$eq": "digestive system"} }, include_metadata=True, include_values=False ) ``` ```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/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const queryResponse = await index.namespace('example-namespace').query({ vector: [0.0236663818359375,-0.032989501953125,...,-0.01041412353515625,0.0086669921875], topK: 3, filter: { "category": { "$eq": "digestive system" } } includeValues: false, includeMetadata: true, }); ``` ```java Java theme={null} import com.google.protobuf.Struct; import com.google.protobuf.Value; import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices; import java.util.Arrays; import java.util.List; public class QueryExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); List query = Arrays.asList(0.0236663818359375f, -0.032989501953125f, ..., -0.01041412353515625f, 0.0086669921875f); Struct filter = Struct.newBuilder() .putFields("category", Value.newBuilder() .setStructValue(Struct.newBuilder() .putFields("$eq", Value.newBuilder() .setStringValue("digestive system") .build())) .build()) .build(); QueryResponseWithUnsignedIndices queryResponse = index.query(1, query, null, null, null, "example-namespace", filter, false, true); System.out.println(queryResponse); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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/manage-data/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) } queryVector := []float32{0.0236663818359375,-0.032989501953125,...,-0.01041412353515625,0.0086669921875} metadataMap := map[string]interface{}{ "category": map[string]interface{}{ "$eq": "digestive system", } } metadataFilter, err := structpb.NewStruct(metadataMap) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } res, err := idxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{ Vector: queryVector, TopK: 3, MetadataFilter: metadataFilter, IncludeValues: false, includeMetadata: true, }) if err != nil { log.Fatalf("Error encountered when querying by vector: %v", err) } else { fmt.Printf(prettifyStruct(res)) } } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/query" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "vector": [0.0236663818359375,-0.032989501953125,...,-0.01041412353515625,0.0086669921875], "namespace": "example-namespace", "topK": 3, "filter": {"category": {"$eq": "digestive system"}}, "includeMetadata": true, "includeValues": false }' ``` ## Metadata filter expressions Pinecone's filtering language supports the following operators: | Operator | Function | Supported types | | :-------- | :------------------------------------------------------------------------------------------------------------------------- | :---------------------- | | `$eq` | Matches with metadata values that are equal to a specified value. Example: `{"genre": {"$eq": "documentary"}}` | Number, string, boolean | | `$ne` | Matches with metadata values that are not equal to a specified value. Example: `{"genre": {"$ne": "drama"}}` | Number, string, boolean | | `$gt` | Matches with metadata values that are greater than a specified value. Example: `{"year": {"$gt": 2019}}` | Number | | `$gte` | Matches with metadata values that are greater than or equal to a specified value. Example:`{"year": {"$gte": 2020}}` | Number | | `$lt` | Matches with metadata values that are less than a specified value. Example: `{"year": {"$lt": 2020}}` | Number | | `$lte` | Matches with metadata values that are less than or equal to a specified value. Example: `{"year": {"$lte": 2020}}` | Number | | `$in` | Matches with metadata values that are in a specified array. Example: `{"genre": {"$in": ["comedy", "documentary"]}}` | String, number | | `$nin` | Matches with metadata values that are not in a specified array. Example: `{"genre": {"$nin": ["comedy", "documentary"]}}` | String, number | | `$exists` | Matches with the specified metadata field. Example: `{"genre": {"$exists": true}}` | Number, string, boolean | | `$and` | Joins query clauses with a logical `AND`. Example: `{"$and": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}` | - | | `$or` | Joins query clauses with a logical `OR`. Example: `{"$or": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}` | - | Only `$and` and `$or` are allowed at the top level of the query expression. 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](/reference/api/database-limits#metadata-filter-limits). For example, the following has a `"genre"` metadata field with a list of strings: ```JSON JSON theme={null} { "genre": ["comedy", "documentary"] } ``` This means `"genre"` takes on both values, and requests with the following filters will match: ```JSON JSON theme={null} {"genre":"comedy"} {"genre": {"$in":["documentary","action"]}} {"$and": [{"genre": "comedy"}, {"genre":"documentary"}]} ``` However, requests with the following filter will **not** match: ```JSON JSON theme={null} { "$and": [{ "genre": "comedy" }, { "genre": "drama" }] } ``` Additionally, requests with the following filters will **not** match because they are invalid. They will result in a compilation error: ```json JSON theme={null} # INVALID QUERY: {"genre": ["comedy", "documentary"]} ``` ```json JSON theme={null} # INVALID QUERY: {"genre": {"$eq": ["comedy", "documentary"]}} ``` # Full-text search Source: https://docs.pinecone.io/guides/search/full-text-search Upsert and search typed JSON documents in Pinecone with BM25 scoring, Lucene query syntax, dense and sparse vector ranking, and metadata filters. Full-text search is in [public preview](#public-preview). APIs may continue to evolve before general availability. You can also use the Pinecone console to create indexes with document schemas, upsert documents, search documents, and fetch or delete documents by ID. Full-text search ranks documents by keyword and phrase relevance using **BM25** scoring, with optional **Lucene** query syntax. Because an index with a document schema can also declare dense and sparse vector fields, the same index can rank by semantic or sparse-vector similarity, so one index can cover keyword and semantic search. **When to use it.** Reach for full-text search when exact words, phrases, names, codes, or identifiers matter, not just semantic similarity. For semantic-only or vector-only workloads, an [index with dense vectors](/guides/get-started/concepts#index-with-dense-vectors) (the vector API) is simpler; see [Search overview](/guides/search/search-overview) to choose the right approach. ### Capabilities What full-text search does and doesn't match: | Capability | Status | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Fuzzy matching (typo tolerance) | Supported in `query_string` queries only ([query syntax](#query-syntax-reference)) | | Stemming | Supported, opt-in per field at index creation ([stemming](#stemming)) | | Stop-word removal | Supported, opt-in per field at index creation ([tokens & analyzers](#tokens-and-analyzers)) | | Substring / n-gram matching | Supported, opt-in per field at index creation. Can't be combined with stemming or stop words on the same field ([n-grams](#substring-search-with-n-grams)) | | Synonym expansion | Not supported. A search for `car` won't match a document containing only `automobile`. Use [semantic search](/guides/search/semantic-search) or [hybrid search](/guides/search/hybrid-search) for synonyms or paraphrases. | **The path, end to end.** Create an index with a [schema](#schema-definition) that declares your ranking fields, upsert your data as JSON documents, then search by choosing one ranking signal per search request with `score_by`. The [end-to-end example](#end-to-end-example) below stitches all three steps into one runnable script, and the sections after it cover each operation in detail. Pinecone's document API stores typed fields you declare in a schema. How it works: 1. You upsert data as JSON **documents**. 2. You declare how each field should be indexed via a **schema** — as a `string` field with `full_text_search` enabled (BM25 scoring), a `dense_vector` field, or a `sparse_vector` field. The schema is for ranking fields only; metadata fields are not declared. 3. Pinecone indexes each field's content according to the type of the field declared in the schema. Any other fields on the upserted documents are automatically stored and indexed for filtering — no schema declaration required. Supported schema field types: * **Text fields** (`type: "string"` with a `full_text_search` config object — for example, `{ "language": "en" }`; `{}` is also valid and uses the same defaults) — indexed for BM25 ranking and Lucene queries. * **Dense vector fields** (`type: "dense_vector"`) — indexed for ANN similarity search. * **Sparse vector fields** (`type: "sparse_vector"`) — indexed for sparse vector similarity search. Filterable metadata is not part of the schema. Any field you upsert that is not declared in the schema is stored on the document, returned via `include_fields`, and automatically indexed for filtering — see [Metadata fields](#metadata-fields). **Every search picks exactly one ranking signal.** The `score_by` clause selects the scoring method for the request: * `text` — BM25 token matching on a single FTS-enabled `string` field. * `query_string` — Lucene query syntax across one or more FTS-enabled `string` fields, including cross-field boolean queries. * `dense_vector` — vector similarity against a `dense_vector` field. * `sparse_vector` — sparse-vector similarity against a `sparse_vector` field. The same index can support all four when the schema declares the corresponding fields, but a given request commits to one. To narrow the candidates a vector ranking sees, combine the `score_by` with a metadata filter — including the text-match operators `$match_phrase`, `$match_all`, and `$match_any` on FTS-enabled `string` fields, plus the standard logical and comparison operators (`$and`, `$or`, `$not`, `$exists`, etc.). The filter narrows what's eligible; the `score_by` ranks what remains. This is the most common hybrid pattern. For example, on an index whose schema declares both a `dense_vector` field (`review_embedding`) and an FTS-enabled `string` field (`review_text`), this single request runs semantic search across the corpus but only over documents whose `review_text` contains the exact phrase "beautifully written": ```python Python theme={null} index.documents.search( namespace="reviews", top_k=5, score_by=[ { "type": "dense_vector", "field": "review_embedding", "values": query_embedding, } ], filter={"review_text": {"$match_phrase": "beautifully written"}}, ) ``` The dense ranking still controls the order of results; the text-match filter just narrows what's eligible to be ranked. ### End-to-end example A complete run from index creation through search. Copy this into a single file, set `PINECONE_API_KEY`, and run. ```python Python theme={null} import os import time from pinecone import Pinecone from pinecone.preview import SchemaBuilder pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) # 1. Create an index. Setting `full_text_search` on a `string` field enables BM25. schema = ( SchemaBuilder() .add_string_field(name="title", full_text_search={"language": "en"}) .add_string_field(name="body", full_text_search={"language": "en"}) .build() ) pc.preview.indexes.create(name="articles-quickstart", schema=schema) # Wait for the index to be ready before upserting (no timeout — add a loop cap in production). while not pc.preview.indexes.describe(name="articles-quickstart").status.ready: time.sleep(2) index = pc.preview.index(name="articles-quickstart") # 2. Upsert documents. Fields declared in the schema (`title`, `body`) are # BM25-indexed; any extra fields (`category`, `year`) are stored on the # document and auto-indexed for filtering as metadata. index.documents.upsert( namespace="example-namespace", documents=[ { "_id": "doc1", "title": "Machine learning in 2024", "body": "Machine learning models are revolutionizing natural language processing", "category": "technology", "year": 2024, }, { "_id": "doc2", "title": "Vector databases", "body": "Vector databases enable fast similarity search across embeddings", "category": "technology", "year": 2023, }, { "_id": "doc3", "title": "Quantum computing", "body": "Quantum computers leverage superposition for faster computation", "category": "science", "year": 2024, }, ], ) # 3. Search with BM25 ranking on `body`, narrowed by a metadata filter and a # phrase-match text filter on the FTS field. The relevance score comes back # as `_score` (not `score`). response = index.documents.search( namespace="example-namespace", top_k=5, score_by=[ { "type": "text", "field": "body", "query": "machine learning", } ], filter={ "year": {"$gte": 2024}, "body": {"$match_phrase": "natural language"}, }, include_fields=["title", "body", "category", "year"], ) for match in response.matches: print(match._id, match._score, getattr(match, "title", "")) ``` What each piece does: * **`SchemaBuilder().add_string_field(..., full_text_search={"language": "en"})`** declares a BM25-indexed text field. Without `full_text_search`, the `string` field would be rejected at index creation — schemas only declare ranking fields. * **`index.documents.upsert(...)`** writes plain JSON documents. Schema fields are validated; non-schema fields (`category`, `year` here) are stored and auto-indexed for filtering. * **`score_by=[{"type": "text", ...}]`** picks BM25 as the ranking method. One ranking method per request; combine ranking with text matching via `filter` rather than mixing score methods. * **`filter`** narrows candidates *before* ranking. Standard operators (`$eq`, `$gte`, etc.) apply to any metadata field; the text-match operators (`$match_phrase`, `$match_all`, `$match_any`) only apply to FTS-enabled `string` fields. * **`_score`** is the system-owned relevance score. A user metadata field named `score` would be returned alongside, untouched. The Python SDK reference further down covers every operation individually; the example above stitches the most common path into one runnable script. ### Filters vs. scoring Filters are deterministic — each document either matches or it doesn't — and they apply before scoring. Scoring methods (`text`/BM25, `query_string`/Lucene, `dense_vector`, `sparse_vector`) order whatever remains after filtering, and only the top `top_k` hits are returned (max 10,000). When you're combining text matching with vector ranking, start with the hard yes/no constraints as filters (including the text-match operators `$match_phrase`, `$match_all`, `$match_any` on FTS-enabled `string` fields), then pick a `score_by` method to rank whatever remains. Use BM25 (`score_by` `text` or `query_string`) when keyword and phrase ranking *order* matters, not just inclusion. An index with a document schema can store both `dense_vector` and `sparse_vector` fields, plus one or more `string` fields with `full_text_search` enabled. A single search request scores results with one ranking method at a time: dense vector, sparse vector, BM25 text, or Lucene query syntax. You can still combine vector ranking with full-text keyword matching in one request by using a text-match filter, such as `$match_phrase`, `$match_all`, or `$match_any`. The vector search ranks the matching documents; the full-text filter narrows the set of documents to search. ## Schema definition The schema is required at index creation and declares the fields that drive ranking or vector search. Filterable metadata is not declared in the schema — any field you upsert that is not declared in the schema is automatically stored and indexed for filtering. **Schema field types:** | Type | Purpose | Key options | | --------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | `dense_vector` | ANN similarity search | `dimension` (required), `metric` (`cosine`, `dotproduct`, `euclidean`) | | `sparse_vector` | Sparse-vector similarity search with values from a custom sparse encoder | — | | `string` (text) | Full-text search. Set `full_text_search` to enable BM25 — for example, `{ "language": "en" }`, or `{}` for defaults. | `language`, `stemming`, `stop_words`, `ngram` (all optional, under `full_text_search`) | Schemas can only declare ranking fields. Declaring a metadata-only field (a `string` field without `full_text_search`, or a `string_list`, `float`, or `boolean` field) is rejected at index creation with a 400 error. Metadata fields are auto-indexed at upsert time. See [Metadata fields](#metadata-fields). **Reserved names.** Field names must be unique, non-empty strings, and **must not start with `_` or `$`**. The `_` prefix is reserved for system-managed fields (for example, `_id`, `_score`); `$` is reserved for filter operators. Field names are also limited to **64 bytes**. Every document has a required `_id` field, which carries its unique identifier. A user metadata field named `score` is allowed — match scores are returned as `_score` to avoid collisions. In public preview, indexes with document schemas do not support integrated inference fields such as `semantic_text`. To use dense or sparse vector ranking in an index with a document schema, declare a `dense_vector` or `sparse_vector` field and provide vector values at upsert time. A `string` field with `full_text_search` is not metadata and does not count toward the 40 KB metadata limit for records. Use these FTS-enabled `string` fields for searchable chunk text. In public preview, indexes with document schemas do not support combining integrated inference fields, such as `semantic_text` fields, with full-text-search fields. To combine semantic ranking with full-text search, declare a `dense_vector` field alongside one or more FTS-enabled `string` fields and provide dense vector values when you upsert documents. **Example: text-only schema** (minimal `{}` enables FTS with all defaults; sub-fields like `language`, `stemming`, and `stop_words` are optional overrides) ```json theme={null} { "name": "articles", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "title": { "type": "string", "full_text_search": { "language": "en" } }, "body": { "type": "string", "description": "The main body text of the article", "full_text_search": { "language": "en", "stemming": true, "stop_words": true } } } } } ``` Including `full_text_search`, even an empty object `{}`, is what turns full-text search on for a `string` field. Without it, the field is rejected at index creation, because schemas only declare ranking fields. **Example: text + dense + sparse vector (multi-field) schema** ```json theme={null} { "name": "articles-hybrid", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "title": { "type": "string", "full_text_search": { "language": "en" } }, "body": { "type": "string", "full_text_search": { "language": "en" } }, "embedding": { "type": "dense_vector", "dimension": 1536, "metric": "cosine" }, "sparse_embedding": { "type": "sparse_vector" } } } } ``` Documents upserted into either schema can carry additional fields — for example, `category` (string), `tags` (array of strings), `year` (number), or `in_stock` (boolean). These fields are stored on the document, returned via `include_fields`, and automatically indexed for filtering. They do not need to be declared in the schema. ### Metadata fields Metadata fields are **not declared in the schema**. Any field you include on an upserted document that is not declared in the schema is treated as metadata: it is stored on the document, returned via `include_fields`, and automatically indexed for filtering with the standard operators (`$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$exists`, `$and`, `$or`, `$not`). Metadata field types are inferred from the values you upsert: strings, numbers (stored as floating point), booleans, and arrays of strings are all supported. You can mix metadata field types across documents in the same index. Schema migration is not yet supported. Once an index is created, you cannot add, remove, or modify fields. Plan your schema carefully. ## API and SDK reference Full-text search uses API version `2026-01.alpha`. All requests require the header `X-Pinecone-Api-Version: 2026-01.alpha`. The endpoints below are split into control-plane operations (project-scoped, authenticated against `api.pinecone.io`) and data-plane operations (index-scoped, authenticated against the per-index `INDEX_HOST.svc..pinecone.io` host returned by `DescribeIndex`). The preview SDK reflects the same split: `pc.preview.*` for control-plane FTS operations and `pc.preview.index(...).documents.*` for data-plane document operations. ### Control plane operations Control plane operations manage indexes and their configuration. Creates a new index with the provided schema. The index initializes asynchronously; poll the describe endpoint to know when it's ready for data operations. **Example request — on-demand read capacity (default)** ```bash theme={null} curl -X POST "https://api.pinecone.io/indexes" \ -H "Api-Key: {{YOUR_API_KEY}}" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-01.alpha" \ -d '{ "name": "articles", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "title": { "type": "string", "full_text_search": { "language": "en" } }, "body": { "type": "string", "full_text_search": { "language": "en" } } } }, "read_capacity": { "mode": "OnDemand" }, "deletion_protection": "disabled" }' ``` **Example request — dedicated read capacity** ```bash theme={null} curl -X POST "https://api.pinecone.io/indexes" \ -H "Api-Key: {{YOUR_API_KEY}}" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-01.alpha" \ -d '{ "name": "articles-dedicated", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "content": { "type": "string", "full_text_search": { "language": "en" } } } }, "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 1, "replicas": 1 } } }, "deletion_protection": "disabled" }' ``` Request parameters: * `name` (string, optional) - Unique index name (lowercase alphanumeric and hyphens, 1-45 characters). Auto-generated if omitted. * `deployment` (object, optional) - Deployment configuration. Defaults to `managed` on AWS `us-east-1` if omitted. * `deployment_type` (string) - `"managed"` for serverless, `"pod"` for pod-based, `"byoc"` for bring-your-own-cloud. * For `managed`: `cloud` (`"aws"` | `"gcp"` | `"azure"`), `region` (e.g., `"us-east-1"`). * `schema` (object, required) - Schema definition. See [Schema definition](#schema-definition) for all supported field types. Each field in `schema.fields` uses the `type` discriminator to select its configuration: * `dense_vector`: `dimension` (required), `metric` (required, one of `cosine`, `dotproduct`, `euclidean`). * `sparse_vector`: no additional options. * `string` (text): `full_text_search: { ... }` (object); optional sub-fields `language`, `stemming`, `stop_words`, and `ngram` (`{ min_gram, max_gram, prefix_only }`, for [substring search](#substring-search-with-n-grams)). * Any field may also include an optional `description` (string) — free-text documentation of what the field contains. It's stored on the schema and returned by describe-index, and is especially useful for agentic workflows where an LLM inspects the schema to decide how to query the index. Metadata-only fields (`string` without `full_text_search`, `string_list`, `float`, `boolean`) are not allowed in the schema and are rejected at index creation. Metadata fields are auto-indexed for filtering at upsert time — see [Metadata fields](#metadata-fields). * `read_capacity` (object, optional) - Read capacity for serverless (managed) indexes: * `mode: "OnDemand"` — default; auto-scaled shared read capacity. * `mode: "Dedicated"` — provisioned read nodes. Requires a `dedicated` block with `node_type`, `scaling`, and (for `Manual` scaling) `manual: { shards, replicas }`. * `deletion_protection` (string, optional) - `"enabled"` or `"disabled"` (default: `"disabled"`). * `tags` (object, optional) - Key-value tags for the index. **Schema constraints:** * Field names must be unique within the schema. * Field names must contain only alphanumeric characters and underscores, must not start with `_` (reserved for system-managed fields like `_id` and `_score`) or `$` (reserved for filter operators), and must be at most 64 bytes. * The schema must contain at least one field. **Example response** **Status:** 201 Created ```json theme={null} { "id": "e51ea4e1-2dda-4607-94dc-9054b1fa8492", "name": "articles", "host": "articles-jweaq8m.svc.aped-4627-b74a.pinecone.io", "status": { "ready": false, "state": "Initializing" }, "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1", "environment": "aped-4627-b74a" }, "schema": { "version": "v1", "fields": { "title": { "type": "string", "description": null, "full_text_search": { "language": "en", "stemming": false, "stop_words": false, "lowercase": true, "max_token_length": 40 } }, "body": { "type": "string", "description": null, "full_text_search": { "language": "en", "stemming": false, "stop_words": false, "lowercase": true, "max_token_length": 40 } } } }, "read_capacity": { "mode": "OnDemand", "status": { "state": "Ready" } }, "tags": null, "deletion_protection": "disabled" } ``` The response shows fields with **server-applied defaults**. Each FTS-enabled field's `full_text_search` block returns the full resolved analyzer config: the settable subset (`language`, `stemming`, `stop_words`) reflects what was passed at index creation (or its default when omitted), and `lowercase` and `max_token_length` are server-applied defaults that aren't settable from the request. All fields include `description` (`null` if not supplied at creation). Wait for `status.ready: true` before performing data plane operations. For `Dedicated` read capacity, also wait for `read_capacity.status.state: "Ready"`. Response fields: * `id` (string) — Unique index ID. * `name` (string) — Index name. * `host` (string) — Per-index host URL for data-plane operations (`INDEX_HOST.svc..pinecone.io`). * `status` (object) — Provisioning status. * `ready` (boolean) — Whether the index is ready for data-plane operations. * `state` (string) — Current state, e.g., `"Initializing"`, `"Ready"`. * `deployment` (object) — Resolved deployment configuration. * `deployment_type` (string) — e.g., `"managed"`. * `cloud` (string) — Cloud provider. * `region` (string) — Region code. * `environment` (string) — Environment identifier assigned by the system. * `schema` (object) — Resolved schema with server-applied defaults. * `version` (string) — Schema version, e.g., `"v1"`. * `fields` (object) — Map of field name → resolved field definition. See note above on `full_text_search` server-applied defaults. * `read_capacity` (object) — Resolved read capacity configuration. * `mode` (string) — `"OnDemand"` or `"Dedicated"`. * `dedicated` (object, present when `mode: "Dedicated"`) — Dedicated read-node configuration: `node_type`, `scaling`, and (for `Manual` scaling) `manual.{ shards, replicas }`. * `status` (object) — Read-capacity provisioning status. * `state` (string) — e.g., `"Migrating"`, `"Ready"`. * `current_shards` (integer or null, `Dedicated` only) — Current number of provisioned shards. * `current_replicas` (integer or null, `Dedicated` only) — Current number of provisioned replicas. * `tags` (object or null) — Key-value tags, or `null` if none. * `deletion_protection` (string) — `"enabled"` or `"disabled"`. Returns all indexes in the project, including their current status and configuration. ```bash theme={null} curl -X GET "https://api.pinecone.io/indexes" \ -H "Api-Key: {{YOUR_API_KEY}}" \ -H "X-Pinecone-Api-Version: 2026-01.alpha" ``` **Status:** 200 OK. Returns an array of index objects, each with the same structure as the create-index response. Returns detailed information about a specific index, including its schema, status, and host URL. ```bash theme={null} curl -X GET "https://api.pinecone.io/indexes/articles" \ -H "Api-Key: {{YOUR_API_KEY}}" \ -H "X-Pinecone-Api-Version: 2026-01.alpha" ``` **Status:** 200 OK. Returns the same structure as the create-index response. Updates index configuration. Currently, only `deletion_protection` can be updated. ```bash theme={null} curl -X PATCH "https://api.pinecone.io/indexes/articles" \ -H "Api-Key: {{YOUR_API_KEY}}" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-01.alpha" \ -d '{ "deletion_protection": "enabled" }' ``` **Status:** 200 OK. Returns the updated index configuration. Permanently deletes an index and all its data. If `deletion_protection` is enabled, you must first disable it using the update endpoint. ```bash theme={null} curl -X DELETE "https://api.pinecone.io/indexes/articles" \ -H "Api-Key: {{YOUR_API_KEY}}" \ -H "X-Pinecone-Api-Version: 2026-01.alpha" ``` **Status:** 202 Accepted (empty body). ### Data plane operations Data plane operations include a namespace in the URL path. Namespaces partition documents within an index: they're auto-created on first upsert and completely isolated from each other. Use `"__default__"` if you don't need partitioning. If your documents are in another namespace, search, fetch, and delete requests must target that namespace. Inserts or updates documents. If a document with the same `_id` exists, it is completely replaced. Documents are indexed asynchronously and may not be searchable immediately after upsert. **Example request** ```bash theme={null} curl -X POST "https://articles-abc123.svc.us-east-1.pinecone.io/namespaces/__default__/documents/upsert" \ -H "Api-Key: {{YOUR_API_KEY}}" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-01.alpha" \ -d '{ "documents": [ { "_id": "doc1", "title": "Machine learning in 2024", "body": "Machine learning models are revolutionizing natural language processing", "category": "technology", "year": 2024 }, { "_id": "doc2", "title": "Vector databases", "body": "Vector databases enable fast similarity search across embeddings", "category": "technology", "year": 2023 }, { "_id": "doc3", "title": "Quantum computing", "body": "Quantum computers leverage superposition for faster computation", "category": "science", "year": 2024 } ] }' ``` Path parameters: * `namespace` (string, required) - Namespace name (use `"__default__"` if not using namespaces). Body parameters: * `documents` (array, required, 1-1000 items) - Array of documents to upsert. Each document is an object with: * `_id` (string, required) - Unique document ID. If a document with this `_id` already exists, it is replaced entirely. If multiple documents in the same batch share an `_id`, only the last one is stored. * Fields matching your schema. Additional fields are stored on the document and auto-indexed for filtering as metadata. Names starting with `_` or `$` are rejected. Limits: * Each upsert request can contain up to 1000 documents and must be no larger than 2 MB. * Each document can be no larger than 2 MB. * Each `full_text_search` string field can be no larger than 100 KB and can contain up to 10,000 tokens. * Each token can be no larger than 256 bytes before analyzer truncation. * Metadata fields on a document (everything outside FTS-enabled `string` fields) are limited to 40 KB per document in total. This metadata limit does not apply to `full_text_search` text fields. **Example response** **Status:** 202 Accepted ```json theme={null} { "upserted_count": 3 } ``` Response fields: * `upserted_count` (integer) - Number of documents accepted for upsert. #### Schema validation Each item in the `documents` array is validated against your index schema. If any item fails validation, **the entire request fails** and nothing is upserted. | Scenario | Result | | -------------------------------------------------------------------- | ----------------------------------------------------------------- | | Field value doesn't match declared type (for schema-declared fields) | **Error** — request fails | | Document or request exceeds a size or count limit | **Error** — request fails | | Field not in schema | Stored on the document and auto-indexed for filtering as metadata | | Field name starts with `_` or `$` | **Error** — request fails | | Schema field missing from item | OK — schema fields are optional unless stated otherwise | | Document missing `_id` | **Error** — request fails | Searches documents using any one of four scoring methods: BM25 token matching (`text`), Lucene query syntax (`query_string`), dense vector similarity (`dense_vector`), or sparse vector similarity (`sparse_vector`). Optionally filter by field values before scoring. To populate an initial view before a user enters a query, use `query_string` with `query: "*"`. This returns `top_k` documents in an arbitrary order; it is not relevance-ranked keyword search. **Example request** ```bash theme={null} curl -X POST "https://articles-abc123.svc.us-east-1.pinecone.io/namespaces/__default__/documents/search" \ -H "Api-Key: {{YOUR_API_KEY}}" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-01.alpha" \ -d '{ "include_fields": ["title", "body", "category", "year"], "score_by": [{ "type": "text", "field": "body", "query": "machine learning" }], "top_k": 10 }' ``` Path parameters: * `namespace` (string, required) - Namespace name (use `"__default__"` if not using namespaces). Body parameters: * `include_fields` (array, optional) - List of field names to return in results. Defaults to `[]` if omitted (or `null`); each match then returns only `_id` and `_score` with no stored fields. Use `["*"]` to return all stored fields (including fields not declared in the schema). User metadata fields named `score` are returned alongside the system-owned `_score` match score. * `score_by` (array, required) - Array of scoring methods. A single search request ranks by one scoring type. Multi-field BM25 is supported: pass several `text` clauses (one per field) or use a single `query_string` clause whose query targets multiple fields, and every contributing field weighs equally; there is no per-clause weight parameter. To combine BM25 ranking with `dense_vector` or `sparse_vector` ranking, restrict the dense (or sparse) search with a text-match filter on the lexical field (`$match_phrase`, `$match_all`, `$match_any`) or run separate searches and merge results client-side. Each item must be one of: * **`type: "text"`** — BM25 token matching on a single text field. Multi-word queries use OR-style matching (case-insensitive). Phrase constraints are not supported here; use `query_string` with quoted terms for exact-phrase ranking. * `field` (string, required) — Name of a text-searchable field. * `query` (string, required) — One or more words to search for. * **`type: "query_string"`** — Lucene query syntax. Supports boolean operators, phrase prefix matching, boosting, fuzzy matching (`term~`, `term~N`), and cross-field queries. * `query` (string, required) — A Lucene query string (see [query syntax reference](#query-syntax-reference)). Target a specific field with Lucene field qualifiers directly in the query string: `notes:friendship`, or combine fields with boolean operators: `title:(alpha) OR body:(beta)`. The query runs against all text-searchable fields in the index when no field qualifier is specified. `query_string` does not accept a `field` or `fields` parameter. Passing either returns a `400` error. Use Lucene field qualifiers in the query string itself to target specific fields: `fieldname:value` or `fieldname:(multi word value)`. * **`type: "dense_vector"`** — Dense vector similarity ranking. Requires a `dense_vector` field in the schema. * `field` (string, required) — Name of the dense-vector field to score against. * `values` (array of floats, required) — Query vector. * **`type: "sparse_vector"`** — Sparse vector similarity ranking. Requires a `sparse_vector` field in the schema. * `field` (string, required) — Name of the sparse-vector field to score against. * `sparse_values` (object, required) — `{ "indices": [...], "values": [...] }`. * `top_k` (integer, required) - Number of results to return (1-10000). * `filter` (object, optional) - Filter conditions applied before scoring. Filter on any metadata field on your documents (auto-indexed at upsert time) or use the text match operators (`$match_phrase`, `$match_all`, `$match_any`) on FTS-enabled `string` fields. Supports the filter operators below. **Search limits:** | Limit | Value | Description | | ---------------------------- | ------ | ------------------------------------------------------------------------------ | | Max `score_by` clauses | 100 | Maximum number of clauses in the `score_by` array | | Max total `score_by` payload | 100 KB | Maximum encoded size of all `score_by` clauses combined | | Max per-clause query size | 10 KB | Maximum size of the `query` string in a single `text` or `query_string` clause | #### Filter operators Filters are applied *before* the search runs. The search only considers documents that match the filter. | Operator | Example | Description | | --------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `$eq` | `{"category": {"$eq": "tech"}}` | Equals | | `$ne` | `{"category": {"$ne": "tech"}}` | Not equals | | `$gt` | `{"year": {"$gt": 2023}}` | Greater than | | `$gte` | `{"year": {"$gte": 2023}}` | Greater than or equal | | `$lt` | `{"year": {"$lt": 2025}}` | Less than | | `$lte` | `{"year": {"$lte": 2025}}` | Less than or equal | | `$in` | `{"category": {"$in": ["a", "b"]}}` | In list | | `$nin` | `{"category": {"$nin": ["a", "b"]}}` | Not in list | | `$exists` | `{"category": {"$exists": true}}` | Field has a value (`true`) or is absent (`false`). | | `$match_phrase` | `{"body": {"$match_phrase": "machine learning"}}` | Exact phrase match (contiguous tokens) on a text-searchable field. Compose with any `score_by` type. | | `$match_all` | `{"body": {"$match_all": "machine learning"}}` | All tokens present, in any order, on a text-searchable field. | | `$match_any` | `{"body": {"$match_any": "AI robotics"}}` | At least one token present, on a text-searchable field. | | `$and` | `{"$and": [{"category": {"$eq": "tech"}}, {"year": {"$gte": 2024}}]}` | Logical AND of the listed clauses. | | `$or` | `{"$or": [{"category": {"$eq": "tech"}}, {"category": {"$eq": "ai"}}]}` | Logical OR of the listed clauses. | | `$not` | `{"$not": {"category": {"$eq": "archive"}}}` | Negation of the wrapped clause. | By default, multiple fields at the top level of a `filter` object are combined with implicit AND semantics. Use `$and`, `$or`, and `$not` to build explicit compound conditions (they can nest). The text match operators (`$match_phrase`, `$match_all`, `$match_any`) share a few rules: * **Where they apply.** Fields declared with a `full_text_search` config object. * **Tokenization.** They reuse the field's configured tokenizer and stemmer — a token that matches in BM25 scoring will match in a text match filter. * **Value limit.** Each operator accepts at most **128 tokens** in its value. * **Lucene-style operators.** Phrase slop (`"phrase"~N`), term boosting (`^N`), and phrase prefix (`"phrase pre"*`) are not parsed — values are literal text and match semantics come from the operator name. To use those operators, score with `query_string`. * **Composition.** They compose freely with metadata operators under `$and`, `$or`, and `$not` at any nesting level: ```json theme={null} { "$and": [ { "body": { "$match_all": "federal reserve" } }, { "category": { "$eq": "finance" } }, { "year": { "$gte": 2024 } } ] } ``` Filters, including text match operators (`$match_phrase`, `$match_all`, `$match_any`), are only valid on `POST /namespaces/{namespace}/documents/search`. The `POST /namespaces/{namespace}/documents/fetch` endpoint is **ID-only**, and `POST /namespaces/{namespace}/documents/delete` accepts only `ids` or `delete_all`. To act on documents matching a metadata expression, search to retrieve matching IDs (capped at `top_k`, max 10,000 per request), then fetch or delete by ID. To remove all documents in a namespace in one call, use `delete_all` instead. #### More examples **Token matching with filter:** ```bash theme={null} curl -X POST "https://articles-abc123.svc.us-east-1.pinecone.io/namespaces/__default__/documents/search" \ -H "Api-Key: {{YOUR_API_KEY}}" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-01.alpha" \ -d '{ "include_fields": ["title", "body", "category", "year"], "filter": { "category": { "$eq": "technology" }, "year": { "$gte": 2024 } }, "score_by": [{ "type": "text", "field": "body", "query": "machine learning" }], "top_k": 10 }' ``` **Cross-field boolean query with `query_string`:** ```bash theme={null} curl -X POST "https://articles-abc123.svc.us-east-1.pinecone.io/namespaces/__default__/documents/search" \ -H "Api-Key: {{YOUR_API_KEY}}" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-01.alpha" \ -d '{ "include_fields": ["title", "body"], "score_by": [{ "type": "query_string", "query": "title:(quantum) OR body:(machine learning)" }], "top_k": 10 }' ``` **Dense vector ranking with a phrase-match filter:** ```bash theme={null} curl -X POST "https://articles-abc123.svc.us-east-1.pinecone.io/namespaces/__default__/documents/search" \ -H "Api-Key: {{YOUR_API_KEY}}" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-01.alpha" \ -d '{ "include_fields": ["title", "body"], "filter": { "body": { "$match_phrase": "machine learning" } }, "score_by": [{ "type": "dense_vector", "field": "embedding", "values": [0.12, 0.34, 0.56] }], "top_k": 10 }' ``` **Sparse vector ranking:** ```bash theme={null} curl -X POST "https://articles-abc123.svc.us-east-1.pinecone.io/namespaces/__default__/documents/search" \ -H "Api-Key: {{YOUR_API_KEY}}" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-01.alpha" \ -d '{ "include_fields": ["title", "body"], "score_by": [{ "type": "sparse_vector", "field": "sparse_embedding", "sparse_values": { "indices": [12, 287, 4096], "values": [0.41, 0.33, 0.18] } }], "top_k": 10 }' ``` **Text match filter with BM25 ranking:** ```bash theme={null} curl -X POST "https://articles-abc123.svc.us-east-1.pinecone.io/namespaces/__default__/documents/search" \ -H "Api-Key: {{YOUR_API_KEY}}" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-01.alpha" \ -d '{ "include_fields": ["body", "category", "year"], "filter": { "$and": [ { "body": { "$match_all": "federal reserve" } }, { "category": { "$eq": "finance" } } ] }, "score_by": [{ "type": "text", "field": "body", "query": "monetary policy impact" }], "top_k": 10 }' ``` This restricts the candidate set to finance articles whose `body` contains both "federal" and "reserve", then ranks those candidates by BM25 score against "monetary policy impact". **Phrase filter with negation:** ```bash theme={null} curl -X POST "https://articles-abc123.svc.us-east-1.pinecone.io/namespaces/__default__/documents/search" \ -H "Api-Key: {{YOUR_API_KEY}}" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-01.alpha" \ -d '{ "include_fields": ["body", "category"], "filter": { "$and": [ { "body": { "$match_phrase": "large language model" } }, { "body": { "$not": { "$match_any": "spam advertisement" } } } ] }, "score_by": [{ "type": "text", "field": "body", "query": "recent advances in generative AI" }], "top_k": 10 }' ``` This requires the exact phrase "large language model" and excludes documents containing "spam" or "advertisement". **Example response** **Status:** 200 OK ```json theme={null} { "matches": [ { "_id": "doc1", "_score": 0.8234, "title": "Machine learning in 2024", "body": "Machine learning models are revolutionizing natural language processing", "category": "technology", "year": 2024 } ], "namespace": "__default__", "usage": { "read_units": 1 } } ``` Response fields: * `matches` (array) - Ranked matches, most relevant first. * `_id` (string) - Document ID. * `_score` (float) - Relevance score (higher is better). The leading underscore prevents collision with user-defined metadata fields named `score`. * Plus any fields requested via `include_fields`. * `namespace` (string) - Namespace searched. * `usage` (object) - `read_units` consumed. Fetches documents by ID. Fetch is **ID-only** — the endpoint does not accept a `filter` parameter. To retrieve documents matching a metadata expression, use `POST /namespaces/{namespace}/documents/search` with a `filter` instead. **Example request — fetch by ids** ```bash theme={null} curl -X POST "https://articles-abc123.svc.us-east-1.pinecone.io/namespaces/__default__/documents/fetch" \ -H "Api-Key: {{YOUR_API_KEY}}" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-01.alpha" \ -d '{ "ids": ["doc1", "doc2"], "include_fields": ["title", "body", "category"] }' ``` Body parameters: * `ids` (array of strings, required, 1-1000 items) - Document IDs to fetch. Must contain at least one ID; an empty array returns a 400 error. * `include_fields` (array of strings, optional) - Field names to include. If omitted, all fields are returned. **Example response** **Status:** 200 OK ```json theme={null} { "documents": { "doc1": { "_id": "doc1", "title": "Machine learning in 2024", "body": "Machine learning models are revolutionizing natural language processing", "category": "technology" }, "doc2": { "_id": "doc2", "title": "Vector databases", "body": "Vector databases enable fast similarity search across embeddings", "category": "technology" } }, "namespace": "__default__", "usage": { "read_units": 2 } } ``` Response fields: * `documents` (object) - Map of document ID to the returned fields (including `_id`). * `namespace` (string) - Namespace fetched from. * `usage` (object) - `read_units` consumed. Deletes documents from a namespace. You must specify exactly one of `ids` or `delete_all`. Delete does not accept a `filter` parameter — to delete documents matching a metadata expression, fetch their IDs via `POST /namespaces/{namespace}/documents/search` first, then pass them to delete. **Example request — delete by ids** ```bash theme={null} curl -X POST "https://articles-abc123.svc.us-east-1.pinecone.io/namespaces/__default__/documents/delete" \ -H "Api-Key: {{YOUR_API_KEY}}" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-01.alpha" \ -d '{ "ids": ["doc1", "doc2"] }' ``` **Example request — delete all in namespace** ```bash theme={null} curl -X POST "https://articles-abc123.svc.us-east-1.pinecone.io/namespaces/__default__/documents/delete" \ -H "Api-Key: {{YOUR_API_KEY}}" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-01.alpha" \ -d '{ "delete_all": true }' ``` Body parameters (specify exactly one): * `ids` (array of strings, 1-1000 items) - Document IDs to delete. * `delete_all` (boolean) - If `true`, delete all documents in the namespace. **Example response** **Status:** 202 Accepted ```json theme={null} {} ``` ## Python SDK For a runnable end-to-end example, see this [Google Colab notebook](https://colab.research.google.com/drive/1lsPeNLCJ2ucbYthHYs9WpybW4nAfB8tG), which demonstrates upserting and searching a sample Wikipedia dataset. ### Installation Full-text search is available in the standard `pinecone` Python SDK under the `pc.preview.*` namespace, which gates the alpha API surface. Make sure you have a recent version of the SDK installed. ```sh theme={null} pip install --upgrade pinecone ``` FTS endpoints are accessed via `pc.preview.*` for control-plane operations and `pc.preview.index(...).documents.*` for data-plane document operations. The `preview` namespace makes the alpha status explicit and isolates FTS APIs from the GA `pc.indexes.*` and `pc.index(...)` namespaces used by the vector API. ### Control plane ```python theme={null} import os from pinecone import Pinecone pc = Pinecone( api_key=os.environ.get('PINECONE_API_KEY') ) ``` ```python theme={null} from pinecone.preview import SchemaBuilder schema = ( SchemaBuilder() .add_string_field(name="title", full_text_search={"language": "en"}) .add_string_field(name="body", full_text_search={"language": "en", "stemming": True}) .build() ) index_model = pc.preview.indexes.create( name="articles", schema=schema, read_capacity={"mode": "OnDemand"}, ) host = index_model.host ``` ```python theme={null} from pinecone.preview import SchemaBuilder schema = ( SchemaBuilder() .add_string_field(name="content", full_text_search={"language": "en"}) .build() ) index_model = pc.preview.indexes.create( name="articles-dedicated", schema=schema, read_capacity={ "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": {"shards": 1, "replicas": 1}, }, }, ) ``` ```python theme={null} index_model = pc.preview.indexes.describe(name="articles") print(index_model.status, index_model.schema) ``` ```python theme={null} for idx in pc.preview.indexes.list(): print(idx.name, idx.status) ``` ```python theme={null} if pc.preview.indexes.exists(name="articles"): index_model = pc.preview.indexes.describe(name="articles") ``` ```python theme={null} pc.preview.indexes.configure( name="articles", deletion_protection="enabled", tags={"env": "prod"}, ) ``` Use `configure` to update mutable settings on an existing index (for example, deletion protection or index tags). Schema changes are not supported in public preview. ```python theme={null} pc.preview.indexes.delete(name="articles") ``` ### Data plane ```python theme={null} index = pc.preview.index(name="articles") ``` ```python theme={null} NAMESPACE = 'example-namespace' docs = [ { "_id": "doc1", "title": "Machine learning in 2024", "body": "Machine learning models are revolutionizing natural language processing", "category": "technology", "year": 2024, }, { "_id": "doc2", "title": "Vector databases", "body": "Vector databases enable fast similarity search across embeddings", "category": "technology", "year": 2023, }, { "_id": "doc3", "title": "Quantum computing", "body": "Quantum computers leverage superposition for faster computation", "category": "science", "year": 2024, }, ] # batch_upsert splits docs into parallel requests — use it for large sets. # For small batches (≤1000 docs), index.documents.upsert(namespace=..., documents=...) is simpler. index.documents.batch_upsert( namespace=NAMESPACE, documents=docs, batch_size=50, max_concurrency=4, show_progress=True, ) ``` ```python theme={null} NAMESPACE = 'example-namespace' response = index.documents.search( namespace=NAMESPACE, top_k=10, score_by=[ { "type": "text", "field": "body", "query": "machine learning", } ], include_fields=["title", "body", "category", "year"], ) for match in response.matches: print(match._id, match._score, getattr(match, "title", "")) ``` ```python theme={null} NAMESPACE = 'example-namespace' response = index.documents.search( namespace=NAMESPACE, top_k=10, score_by=[ { "type": "query_string", "query": "title:(quantum) OR body:(machine learning)", } ], include_fields=["title", "body"], ) ``` ```python theme={null} NAMESPACE = 'example-namespace' query_vector = [0.12, 0.34, ...] # replace with your actual query vector response = index.documents.search( namespace=NAMESPACE, top_k=10, score_by=[ { "type": "dense_vector", "field": "embedding", "values": query_vector, } ], filter={"body": {"$match_phrase": "machine learning"}}, include_fields=["title", "body"], ) ``` ```python theme={null} NAMESPACE = 'example-namespace' response = index.documents.fetch( namespace=NAMESPACE, ids=["doc1", "doc2"], include_fields=["title", "body", "category"], ) for doc_id, doc in response.documents.items(): print(doc_id, getattr(doc, "title", "")) ``` ```python theme={null} NAMESPACE = 'example-namespace' index.documents.delete(namespace=NAMESPACE, ids=["doc1", "doc2"]) index.documents.delete(namespace=NAMESPACE, delete_all=True) ``` Delete is **ID-only** (or `delete_all`) — it does not accept a `filter`. To delete documents matching a metadata expression, search first to get IDs, then pass them to `delete`. ## Bulk import Bulk import loads large numbers of documents into an index from object storage (Amazon S3, Google Cloud Storage, or Azure Blob Storage) in a single asynchronous job. It is the most efficient way to populate an index with many documents at once. For small or ongoing writes, use [`documents.upsert`](#data-plane-operations) instead. For indexes with document schemas, import files are [JSON Lines](https://jsonlines.org/) (`.jsonl`), optionally gzip-compressed (`.jsonl.gz`). This is the equivalent of the Parquet-based [Import records](/guides/index-data/import-data) flow used by indexes without a schema definition: the `start_import`, `describe_import`, `list_imports`, and `cancel_import` operations are identical, and Pinecone selects the file format automatically from the index type. Bulk import is supported for indexes with document schemas in which every field is caller-supplied — full-text `string`, `dense_vector`, `sparse_vector`, and auto-indexed metadata. Semantic-text (auto-embedded) fields are not yet supported in schema. ### File format Each line of a `.jsonl` (or `.jsonl.gz`) file is one JSON document, identical in shape to a document you would pass to [`documents.upsert`](#data-plane-operations). Import validates every document through the same code path as a live upsert, so any document that upserts cleanly imports cleanly. For example, consider an index whose schema declares one full-text field and one dense vector field: ```json theme={null} { "schema": { "fields": { "body": { "type": "string", "full_text_search": { "language": "en" } }, "embedding": { "type": "dense_vector", "dimension": 3, "metric": "cosine" } } } } ``` Each line supplies `_id`, the schema-declared fields, and any additional fields you want stored as filterable metadata (`category` and `year` here): ```jsonl theme={null} {"_id": "doc1", "body": "Machine learning models are revolutionizing natural language processing", "embedding": [0.12, 0.34, 0.56], "category": "technology", "year": 2024} {"_id": "doc2", "body": "Vector databases enable fast similarity search across embeddings", "embedding": [0.91, 0.05, 0.44], "category": "technology", "year": 2023} ``` Each document follows these rules: * `_id` is required in every document: a non-empty string, unique within the namespace. * Searchable fields declared in the schema are encoded by type: * A `dense_vector` field (`embedding` above) is a JSON array of floats whose length equals the schema's declared `dimension`. When the schema declares a dense vector field, every document must include it. * A `sparse_vector` field is an object `{"indices": [...], "values": [...]}`. * A full-text `string` field (`body` above) is a JSON string. * Any other field (`category` and `year` above) is stored on the document and [auto-indexed as filterable metadata](#metadata-fields): a string, number, boolean, or array of strings. An array of numbers in an undeclared field is rejected rather than stored as metadata. * Field names must not start with `_` (reserved for system fields like `_id`) or `$` (reserved for filter operators). The same per-document size limits as [upsert](#data-plane-operations) apply. ### Directory layout Lay files out by namespace, exactly as for [Parquet imports](/guides/index-data/import-data#prepare-your-data): under a common dataset prefix in your bucket or container, create one subdirectory per namespace and place that namespace's `.jsonl` / `.jsonl.gz` files inside it. ``` / └── / ├── namespace1/ │ ├── 0.jsonl │ └── 1.jsonl.gz └── namespace2/ └── 0.jsonl ``` * Each namespace must **not already exist** in the index — imports only create new namespaces. * A namespace subdirectory can mix plain `.jsonl` and gzip-compressed `.jsonl.gz` files. ### Prepare a file Generate a schema-conformant `.jsonl` (or `.jsonl.gz`) file from your documents, then upload it to a namespace subdirectory in object storage. ```python Python theme={null} import gzip import json documents = [ { "_id": "doc1", "body": "Machine learning models are revolutionizing natural language processing", "embedding": [0.12, 0.34, 0.56], # must match the schema dimension "category": "technology", "year": 2024, }, { "_id": "doc2", "body": "Vector databases enable fast similarity search across embeddings", "embedding": [0.91, 0.05, 0.44], "category": "technology", "year": 2023, }, ] # Plain JSONL: one compact JSON document per line. with open("0.jsonl", "w") as f: for doc in documents: f.write(json.dumps(doc) + "\n") # Or gzip-compressed (.jsonl.gz) to cut storage and transfer. with gzip.open("0.jsonl.gz", "wt") as f: for doc in documents: f.write(json.dumps(doc) + "\n") ``` Upload the file to the relevant namespace subdirectory in your bucket or container, e.g. `/namespace1/0.jsonl`. #### Convert Parquet files to JSONL If your data is already stored as Parquet in the [vector import format](/guides/index-data/import-data#prepare-your-data) (`id`, `values`, `sparse_values`, `metadata` columns), convert each file to JSONL for the document schema. Map `id` to `_id`, the vector columns to your schema's field names, and spread the `metadata` JSON string into top-level fields: ```python Python theme={null} import gzip import json import pyarrow.parquet as pq # Your schema's field names DENSE_FIELD = "embedding" # dense_vector field SPARSE_FIELD = "sparse_embedding" # sparse_vector field table = pq.read_table("0.parquet") with gzip.open("0.jsonl.gz", "wt") as f: for row in table.to_pylist(): doc = {"_id": row["id"]} if row.get("values") is not None: doc[DENSE_FIELD] = row["values"] if row.get("sparse_values") is not None: doc[SPARSE_FIELD] = { "indices": row["sparse_values"]["indices"], "values": row["sparse_values"]["values"], } if row.get("metadata"): # Metadata keys become top-level fields. Keys that match a # schema-declared field (e.g. a full-text "body" field) are # validated against the schema; the rest are auto-indexed metadata. doc.update(json.loads(row["metadata"])) f.write(json.dumps(doc) + "\n") ``` ### Start an import To import from a secure data source, you first need a [storage integration](/guides/operations/integrations/manage-storage-integrations) that gives Pinecone access to your object storage. An integration is not required for public data sources. Start the import against the index host with the [`start_import`](/reference/api/latest/data-plane/start_import) operation (`POST /bulk/imports`) — the same endpoint, parameters, and behavior as for [Parquet imports](/guides/index-data/import-data#import-records-into-an-index). Pinecone detects from the index's document schema that the files are JSONL. For `uri`, specify the bucket or container in your storage provider's URI format, plus the dataset prefix — not a path to a single file or a namespace subdirectory. Bulk import is not yet supported in any Pinecone SDK. Use the REST API to start and manage imports. ```bash curl theme={null} # To get the unique host for an index, see # https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/bulk/imports" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-01.alpha" \ -d '{ "integrationId": "a12b3d4c-47d2-492c-a97a-dd98c8dbefde", "uri": "STORAGE_URI/DATASET_PREFIX", "errorMode": { "onError": "continue" } }' ``` The response contains an `id` you can use to track the import with the [`describe_import`](/reference/api/latest/data-plane/describe_import) operation: ```json Response theme={null} { "id": "1" } ``` Imported documents are indexed asynchronously and may not be searchable immediately after the import reports complete. ### Track and manage an import The [`describe_import`](/reference/api/latest/data-plane/describe_import), [`list_imports`](/reference/api/latest/data-plane/list_imports), and [`cancel_import`](/reference/api/latest/data-plane/cancel_import) operations behave the same for document and vector indexes. See [Import records](/guides/index-data/import-data#track-import-progress) for the full request and response shapes and troubleshooting. ```bash curl theme={null} curl -X GET "https://$INDEX_HOST/bulk/imports/1" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-01.alpha" ``` Per-document errors identify the file name, row number, and document `_id`. With `errorMode.onError` set to `continue`, invalid documents are skipped and the rest import — use `records_imported` to see how many loaded; with `abort`, the import stops on the first invalid document. A namespace subdirectory that contains no `.jsonl` / `.jsonl.gz` files is skipped — no namespace is created for it. An import that finds no importable files anywhere under the dataset prefix fails. ### Import limits Document imports share the [import limits](/guides/index-data/import-data#import-limits): up to 10,000 namespaces and 100,000 files per import, up to 10 GB per file, and — for on-demand indexes — up to 1 TB total input data per import. For `.jsonl.gz` files, size limits are checked against an estimated uncompressed size of 10× the compressed file size, so plan for roughly 1 GB per compressed file. ## Tokens and analyzers The word "token" appears in every scoring method, but it means different things in each. Knowing what counts as a token in your chosen method is essential to writing queries that match what you expect. ### FTS tokens (`type: "text"`, `type: "query_string"`, and `$match_*` filters) When you declare a field with `full_text_search: { ... }`, Pinecone runs the field's text through an **analyzer pipeline** at index time and at query time. Both `type: "text"` and `type: "query_string"` use the same pipeline, and the text-match filter operators ([`$match_phrase`, `$match_all`, `$match_any`](#filters-vs-scoring)) reuse it as well — so a token that scores in BM25 will match in a filter on the same field. The pipeline (in order): 1. **Split** the text on whitespace and punctuation. Hyphenated words become multiple tokens (`state-of-the-art` → `state`, `of`, `the`, `art`). 2. **Lowercase** every token. Lowercasing is server-applied and cannot be overridden. 3. **Stem** each token to its root form, if [`stemming`](#stemming) is enabled on the field. The stemmer is selected by the field's [`language`](#language) setting (`models` → `model`, `running` → `run`). 4. **Drop stop words** (common words like `the`, `and`), if `stop_words: true` is set on the field. Not all languages have built-in stop word lists; see the [Language](#language) table for details. 5. **Cap** each token at 40 characters. This cap is server-applied and cannot be overridden. For example, with the `english` analyzer, `stemming: true`, and `stop_words: false`, the input `"State-of-the-Art Models"` becomes the tokens `state`, `of`, `the`, `art`, `model`. Those are the tokens BM25 scores against, and the tokens a `$match_phrase: "art models"` filter will look for. Fields configured for [substring search](#substring-search-with-n-grams) replace this whole-token pipeline with character n-gram tokenization, so a token is further split into overlapping character sequences. ### Dense-vector tokens (`type: "dense_vector"`) Dense embedding models have their own internal tokenizer — usually a subword scheme like BPE, WordPiece, or SentencePiece — that breaks text into pieces the model was trained on. Those tokens are **private to the model**. You never query them directly: a dense search compares the full embedding of a query against the full embedding of a document. The same string can therefore behave very differently in `type: "text"` (which sees the FTS analyzer tokens above) and `type: "dense_vector"` (which sees a single high-dimensional vector). The `$match_*` filter operators do not apply to dense-vector fields. ### Sparse-vector tokens (`type: "sparse_vector"`) Sparse encoders also tokenize internally, and the tokenization depends on the encoder. Pinecone's hosted [`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0) produces learned per-token weights and **expands to related terms** that don't appear in the source text. Encoder tokens are not interchangeable with FTS analyzer tokens, and `$match_*` filters do not apply to sparse-vector fields. ### Practical implication If your application stores the same source text in an FTS-enabled `string` field and also encodes it into a `dense_vector` or `sparse_vector` field, the three representations are tokenized **independently**: the FTS analyzer for the `string` field, and each model's internal tokenizer for the vector fields. Identical query strings will therefore retrieve different documents under different `score_by` types, and `$match_*` filters can only narrow on the FTS-analyzer tokens of FTS-enabled `string` fields. ## Query syntax reference Full-text search supports two text-based query types with different capabilities: | Feature | `type: "text"` | `type: "query_string"` | | ----------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------ | | **Purpose** | Simple token search on one field | Lucene query syntax | | **`fields` parameter** | Required (exactly one field) | Optional (restricts to listed text-searchable fields) | | **Multi-word behavior** | Token match, OR across terms (BM25) | OR by default; use `AND`, quotes, etc. for other logic | | **Boolean operators** | Not supported (treated as words) | `AND`, `OR`, `NOT`, `+`, `-` | | **Phrase prefix** | Not supported | `"phrase pre"*` (last term as prefix) | | **Phrase matching** | Not supported in `score_by` (use `query_string` or `$match_phrase` filter) | Wrap in quotes: `"exact phrase"` | | **Phrase slop** | Not supported | `"phrase"~N` | | **Boosting** | Not supported | `term^N` | | **Regex** | Not supported | `field:/pattern.*/` | | **Fuzzy matching** | Not supported | `term~`, `term~N` (typo tolerance) | | **Stemming** | Supported ([when enabled](#stemming)) | Supported ([when enabled](#stemming)) | | **Case sensitivity** | Case-insensitive | Case-insensitive | ### Token matching (`type: "text"`) With `type: "text"`, the query string is run through the field's analyzer pipeline (see [Tokens and analyzers](#tokens-and-analyzers)) and each resulting term contributes to the BM25 score. Multiple terms use **OR** semantics: documents can match if they contain **any** of the terms; documents that match more terms or stronger term statistics typically rank higher. Matching is case-insensitive. Exact **phrase** constraints (adjacent words in order) belong in `type: "query_string"` using quotes, or in a `$match_phrase` filter. | Query | Matches | Does not match | | ------------------ | --------------------------------------------------------------------- | -------------------------------------- | | `machine learning` | "**Machine** learning is great" (has "machine") | "Vector databases only" (neither term) | | `machine learning` | "We use **learning** and **machine**" (both terms present, any order) | "Vector databases only" (neither term) | | `machine` | "**Machine** learning is great" | "Vector databases only" (no "machine") | **Key behaviors:** * **Single term** (`machine`): Matches documents containing that term. Case-insensitive. * **Multiple terms** (`machine learning`): Each term is searched independently with OR-style matching and combined BM25 scoring — not as a single adjacent phrase. * **No operator support**: Characters like `AND`, `OR`, `NOT`, `*`, `~`, `^`, `+`, `-`, and quotes are treated as literal text. ### Lucene query syntax (`type: "query_string"`) With `type: "query_string"`, you write Lucene query syntax, with operator support. Field names are embedded in the query itself (e.g., `content:(term)`) and can combine multiple fields with boolean operators. | Operator | Syntax | Example | Description | | -------------- | -------------------------- | ----------------------------------- | ----------------------------------------------------------- | | Term | `field:(word)` | `body:(computers)` | Match documents containing term | | Multiple terms | `field:(a b)` | `body:(machine learning)` | OR by default — matches either term | | Phrase | `field:("words")` | `body:("machine learning")` | Exact phrase match (adjacent, in order) | | AND | `AND` | `body:(a AND b)` | Both terms required | | OR | `OR` | `body:(a OR b)` | Either term matches (same as default) | | NOT | `NOT` | `body:(a NOT b)` | Exclude second term | | Required | `+term` | `body:(+database search)` | Term must be present | | Excluded | `-term` | `body:(database -deprecated)` | Term must not be present | | Grouping | `(expr)` | `body:((a OR b) AND c)` | Control precedence | | Phrase slop | `"phrase"~N` | `body:("fast search"~2)` | Allow up to N words between phrase terms | | Boost | `term^N` | `body:(machine^3 learning)` | Multiply term's relevance score by N | | Phrase prefix | `"phrase pre"*` | `body:("james w"*)` | Last term in phrase matched as prefix | | Regex | `field:/pattern.*/` | `body:/comput.*/` | Match documents by regular expression on a field | | Fuzzy | `term~` or `term~N` | `body:(compxter~1)` | Match terms within edit distance N (0–2) for typo tolerance | | Cross-field | `fieldA:(…) OR fieldB:(…)` | `title:(quantum) OR body:(machine)` | Combine clauses across text-searchable fields | A **term** is a single word. Multiple space-separated terms use **OR logic** by default. ``` body:(machine learning) ``` Matches documents containing "machine" OR "learning" (or both). Documents with both terms rank higher. Wrap multiple words in quotes to match them as an exact sequence. ``` body:("machine learning") ``` Matches only documents containing the exact phrase "machine learning" with the words adjacent. That is different from `type: "text"` with `query: "machine learning"`, which uses **token OR** matching on the field. For phrase matching as a **filter** (e.g., composed with dense-vector ranking), use `{"body": {"$match_phrase": "machine learning"}}` in the `filter` block. *Phrase terms are matched against the field's analyzed tokens. If [stemming](#stemming) is enabled on the field, the phrase terms stem too — e.g., `"running fast"` matches `running fast` and `runs fast`.* Use `AND`, `OR`, and `NOT` for explicit boolean logic. ``` body:(machine AND learning) # Both terms required (any order) body:(machine OR learning) # Either term (same as default) body:(machine NOT learning) # "machine" but not "learning" ``` **Precedence:** AND binds tighter than OR. Use parentheses to control order: ``` body:((database OR storage) AND distributed) ``` Use `+` to require a term and `-` to exclude a term. ``` body:(+database distributed) # MUST contain "database", "distributed" optional body:(database -deprecated) # Contains "database", must NOT contain "deprecated" body:(+vector +search -legacy) # MUST have "vector" AND "search", must NOT have "legacy" ``` Allow words in a phrase to appear within N positions of each other. ``` body:("machine learning"~3) ``` Matches "machine learning", "machine deep learning", or "machine-assisted learning" (words within 3 positions). *The phrase terms are matched against analyzed tokens, so [stemming](#stemming) (when enabled on the field) applies here too.* Increase the importance of specific terms in ranking using `^N`. ``` body:(machine^3 learning) # "machine" weighted 3x more than "learning" body:("neural network"^2 deep) # Phrase boosted 2x ``` Documents with boosted terms rank higher when those terms appear. Append `*` to a quoted phrase to treat the last term as a prefix. The phrase must contain at least two terms. ``` body:("james w"*) # Matches "james webb", "james watson", "james wilde" body:("machine lea"*) # Matches "machine learning", "machine learns" ``` Both the literal terms and the prefix are matched against the field's analyzed tokens. If [stemming](#stemming) is enabled on the field, stemming applies to the completed terms in the phrase, while the final prefix is expanded against analyzed tokens. Phrase prefix is optimized for autocomplete-style queries where the final word prefix is reasonably specific. To keep latency low, Pinecone expands the final prefix to the first 50 matching terms in lexicographic order. For example, `"new yor"*` can match `new york`, but `"new yo"*` might not if `york` is not among the first 50 expanded terms for `yo`. Wrap a pattern in forward slashes to match documents by regular expression on a field. ``` body:/comput.*/ ``` Matches documents whose `body` field contains a token matching the regex `comput.*` (e.g., "computer", "computing", "computation"). Regex patterns are matched against individual analyzed tokens, not the raw field text. ``` body:/machin[ei].*/ ``` Matches tokens like "machine" or "machene". Standard Lucene regex syntax is supported. Regex is only available with `type: "query_string"`. It is not supported with `type: "text"`. Append `~` to a bare term to match indexed terms within a small edit distance, so a misspelled query term still matches the intended word. ``` body:(compxter~1) # Matches "computer" (1 edit away) body:(machine~ learning~) # Auto distance per term, based on term length title:(pinecone~2) # Explicit distance 2 ``` * **`term~`** — automatic distance based on the term's length: terms shorter than 4 characters must match exactly, terms of 4–7 characters allow 1 edit, and terms of 8 or more characters allow 2 edits. * **`term~N`** — fixed edit distance `N`, where `N` is `0`, `1`, or `2`. `~0` is an exact match. A distance greater than 2 is a query error (`400`). An "edit" is an inserted, deleted, or substituted character (plain Levenshtein distance). Swapping two adjacent characters counts as 2 edits. Matching is case-insensitive, as with all text queries. Fuzzy matches are scored as a constant; exact matches still contribute their full BM25 score, so an exact hit ranks above a fuzzy hit for the same term. Fuzzy composes with the rest of the query syntax — boolean operators, required/excluded terms, boosts, field qualifiers, and metadata filters. The `~` operator is fuzzy only when it follows a **bare term**. After a quoted phrase, `~N` keeps its [phrase slop](#query-syntax-reference) meaning — for example, `body:("machine learning"~2)` is slop, while `body:(learning~2)` is fuzzy. There is no fuzzy phrase matching. On [stemmed](#stemming) fields, fuzzy matching runs against the stemmed terms and is best-effort: a typo that changes how a word stems may not match. Fuzzy matching is most effective on fields without stemming (the default). Fuzzy is available only with `type: "query_string"`; with `type: "text"`, `~` is treated as a literal character. `query_string` can target multiple fields in the same expression. Use Lucene field qualifiers (`field:(clause)`) directly in the query string; omit them to run against all text-searchable fields: ``` title:(quantum) OR body:(machine learning) ``` Matches documents whose `title` contains "quantum", documents whose `body` contains "machine" or "learning", or both — with BM25 scoring combining across fields. ## Stemming Stemming reduces words to their root form so that morphological variants match each other. For example, with stemming enabled, a query for "run" also matches documents containing "running" or "runs". Stemming is **opt-in** and disabled by default. To enable it, set `stemming: true` on a text-searchable field when creating the index. The stemming algorithm is determined by the field's [`language`](#language) setting. **Example: enabling stemming with French** ```json theme={null} { "schema": { "fields": { "body": { "type": "string", "full_text_search": { "stemming": true, "language": "french" } } } } } ``` Stemming applies to both `type: "text"` and `type: "query_string"` queries on the field. Stemming is set at index creation and cannot be changed afterward. ## Language The `language` parameter controls tokenization and stemming behavior for a text-searchable field. It determines how text is analyzed during indexing and search: how words are split into tokens and, when [stemming](#stemming) is enabled, which language-specific rules are used to reduce words to their root forms. The default language is `"en"` (English). You can specify a language using either its short code or full name (e.g., `"fr"` or `"french"`). **Supported languages:** | Code | Full name | Stop words | | ---- | ------------ | ---------- | | `ar` | `arabic` | No | | `da` | `danish` | Yes | | `de` | `german` | Yes | | `el` | `greek` | No | | `en` | `english` | Yes | | `es` | `spanish` | Yes | | `fi` | `finnish` | Yes | | `fr` | `french` | Yes | | `hu` | `hungarian` | Yes | | `it` | `italian` | Yes | | `nl` | `dutch` | Yes | | `no` | `norwegian` | Yes | | `pt` | `portuguese` | Yes | | `ro` | `romanian` | No | | `ru` | `russian` | Yes | | `sv` | `swedish` | Yes | | `ta` | `tamil` | No | | `tr` | `turkish` | No | Language is set at index creation and cannot be changed afterward. ## Substring search with n-grams By default, full-text search matches whole tokens: a query for `comp` does not match a document containing `computer`. To match substrings (for example, to find `computer` from `comp`, `mput`, or `uter`), configure a text field for **character n-gram** tokenization. With n-gram tokenization, each token is broken into overlapping character sequences (n-grams) at index time, and query text is broken the same way at search time, so a substring of an indexed word matches. This is useful for partial-word matching, autocomplete, and searching identifiers or codes where users type only a fragment. To enable it, set an `ngram` object on a text field's `full_text_search` config at index creation: ```json theme={null} { "schema": { "fields": { "product_name": { "type": "string", "full_text_search": { "ngram": { "min_gram": 3, "max_gram": 4, "prefix_only": false } } } } } } ``` `ngram` parameters: | Parameter | Type | Required | Description | | ------------- | ------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `min_gram` | integer | Yes | Shortest n-gram to generate. Must be at least `1`. | | `max_gram` | integer | Yes | Longest n-gram to generate. Must be at least `min_gram` and at most `10`. | | `prefix_only` | boolean | No (default `false`) | When `true`, generate only n-grams anchored to the start of each token (edge n-grams). Use this for prefix and autocomplete matching. When `false`, generate n-grams at every position for full substring matching. | For example, with `min_gram: 3`, `max_gram: 4`, and `prefix_only: false`, the token `search` is indexed as `sea`, `ear`, `arc`, `rch`, `sear`, `earc`, `arch`. A shorter or longer window changes the tradeoff: smaller n-grams match more loosely and grow the index more; larger n-grams are more precise but require longer matching substrings. **Querying an n-gram field.** No special query syntax is needed. Once a field is configured for n-grams, ordinary `type: "text"` and `query_string` queries against it match on substrings automatically, because the query text is tokenized into the same n-grams as the indexed text: ```python Python theme={null} response = index.documents.search( namespace="example-namespace", top_k=10, score_by=[ { "type": "text", "field": "product_name", "query": "sear", } ], include_fields=["product_name"], ) ``` N-gram tokenization cannot be combined with [`stemming`](#stemming) or `stop_words` on the same field — an index-creation request that sets `ngram` alongside either is rejected with a `400` error. Tokens are always lowercased. Because every position emits a token for each gram length, an n-gram field is larger on disk than a plain text field; keep `min_gram`/`max_gram` as narrow as your matching needs allow. N-gram configuration is set at index creation and cannot be changed afterward. ## Troubleshooting * Check indexing latency: new documents may take up to 1 minute to become searchable; schemas with multiple indexed fields may take slightly longer. * Verify the upsert response shows the expected `upserted_count`. * Confirm you're searching the same namespace where you upserted. * With `type: "text"`, multi-word queries use **token OR** matching — documents need not contain the full phrase. Try a single-term query first to confirm the document is searchable. * If using filters, ensure the document's field values match your filter conditions. Metadata fields are auto-indexed at upsert time, so any field present on a document can be filtered on; filtering on a field that no document contains returns no results. * **`type: "text"` uses OR across terms.** `machine learning` matches documents that contain "machine", "learning", or both (BM25 ranking). For an **exact phrase**, use `type: "query_string"` with `body:("machine learning")` or a `$match_phrase` filter. * **`type: "query_string"` defaults to OR for unquoted terms.** `body:(machine learning)` matches documents containing either term. Use `AND` or `+` for required terms. * Operators like `AND`, `OR`, `NOT`, `*`, `~`, and `^` only work with `type: "query_string"`. With `type: "text"`, they are treated as literal words. Query syntax errors only apply to `type: "query_string"`. With `type: "text"`, any input is valid as a literal string to be tokenized. * Unmatched quotes (`"machine learning`): Close all quotes. * Empty query: Provide at least one search term. * Invalid boolean syntax (`AND machine`): Operators need terms on both sides. * Unbalanced parentheses: Match all opening and closing parens. * Unknown field name: Field names in the query must match text-searchable fields in the schema. * `401 Unauthorized`: Check the `Api-Key` header. * `400 Bad Request`: Check JSON syntax and required fields. Examples: `fields` array with more than one element for `text`/`dense_vector`/`sparse_vector`; missing mutually-exclusive field for Fetch/Delete. * `404 Not Found`: Verify the index name and host URL. * Missing API version: Add `X-Pinecone-Api-Version: 2026-01.alpha`. * Type mismatch: Ensure values match declared schema types. * Invalid `_id`: Every document must have a non-empty `_id` string. * Reserved names: Field names cannot start with `_` (reserved for system-managed fields like `_id` and `_score`) or `$` (reserved for filter operators), and must be at most 64 bytes. * Reduce query complexity: Boolean operators and large phrase slop are more expensive than simple term queries. * Simplify filters: Filters are applied before scoring, so broad filters increase the search space. * For cost-sensitive workloads, use `read_capacity.mode: "Dedicated"` to get predictable latency. When a request is rejected with a 4xx that doesn't seem to match your intent, the cause is usually one of these: * **Sparse-vector `score_by` clauses use `sparse_values`, not `values`.** The `values` key is for `dense_vector`. A sparse clause needs the full object: `"sparse_values": { "indices": [...], "values": [...] }`. * **Every `score_by` clause must include `type`.** It's the discriminator that selects the scoring method (`text`, `query_string`, `dense_vector`, `sparse_vector`). Omitting it returns a 400. * **Every document must have a non-empty `_id` string.** There is no default; the upsert request fails if any document in the batch is missing `_id` or has an empty value. * **Wait for `status.ready: true` before searching.** A newly created index can briefly return empty results. For `Dedicated` read capacity, also wait for `read_capacity.status.state: "Ready"`. * **The match-score response field is `_score`, not `score`.** A user metadata field named `score` is allowed and is returned alongside the system-owned `_score`. * **Namespace is part of the URL path.** Use `__default__` (the literal string) if you don't need partitioning. An empty path segment is rejected. * **`dense_vector` queries use `values`, not `query`.** Only `text` and `query_string` clauses use `query` (a string). `dense_vector` and `sparse_vector` use `values` (a float array) and `sparse_values` (an `{indices, values}` object) respectively. ## Public preview Full-text search is in public preview under API version `2026-01.alpha`. The feature is ready for production evaluation; APIs may continue to evolve before general availability. **Requirements & limitations** * All requests require `X-Pinecone-Api-Version: 2026-01.alpha`. * The REST API, Python SDK (`pinecone`, `pc.preview.*` namespace for FTS control plane), and Pinecone console are the supported entry points for public preview. * **Endpoint compatibility**: indexes with document schemas use the `/namespaces/{namespace}/documents/*` endpoints; dense, sparse, and integrated-inference indexes continue to use `/vectors/*` (and `/records/*` for integrated inference). The two endpoint families are index-type-specific and don't cross over. * Supported deployment modes: managed (serverless) with `read_capacity.mode` of `OnDemand` or `Dedicated`. * Changing an index from dedicated read capacity back to on-demand read capacity is not supported. To move from dedicated read capacity to on-demand, create a new on-demand index and reingest your data. * Schemas declare ranking fields only: text fields (`string` with `full_text_search`), `dense_vector`, and `sparse_vector`. Text-only, text + dense vector, and combined dense + sparse + text schemas are all supported in a single index. Metadata-only field declarations (`string` without `full_text_search`, `string_list`, `float`, `boolean`) are rejected at index creation; metadata is auto-indexed at upsert time. * **Schema and document limits**: a schema can contain up to 100 `full_text_search` string fields; each `full_text_search` string field can be up to 100 KB and 10,000 tokens; tokens can be up to 256 bytes before analyzer truncation; each document can be up to 2 MB; each upsert request can contain up to 1000 documents and 2 MB. * **Metadata size**: metadata fields on a document (everything outside FTS-enabled `string` fields) are limited to 40 KB per document in total. This limit does not apply to `full_text_search` text fields. * **Vector-field cardinality**: a schema can declare up to 100 `string` fields with `full_text_search` enabled, but at most one `dense_vector` field and at most one `sparse_vector` field per index. * **Field-name policy**: schema and metadata field names must not start with `_` (reserved for system-managed fields like `_id` and `_score`) or `$` (reserved for filter operators), and are limited to 64 bytes. * The match-score response field is `_score` (renamed from `score` so that user metadata named `score` can coexist with the system-owned match score in the flat response payload). * **A single search request ranks by one scoring type.** Multi-field BM25 is supported: pass multiple `text` clauses (one per field) or a single `query_string` clause that targets several fields — every contributing field weighs equally in `2026-01.alpha`; there is no per-clause weight parameter. To combine BM25 ranking with `dense_vector` or `sparse_vector` ranking, restrict the dense (or sparse) search with a text-match filter (`$match_phrase`, `$match_all`, `$match_any`) on the lexical field, or run separate searches and merge the results client-side. * Newly upserted documents are indexed asynchronously and may not be searchable immediately. * **No partial / per-field updates**: `POST /namespaces/{namespace}/documents/upsert` always replaces the entire document for a given `_id`. There is no `PATCH` endpoint and no field-level merge in `2026-01.alpha`. To update a single field, fetch the document by ID (`POST /namespaces/{namespace}/documents/fetch`), modify the field client-side, and upsert the full document back under the same `_id`. Field-level merge is on the roadmap for a post-public-preview release. * **Schemas are fixed at index creation.** Adding, removing, or retyping fields after creation is not yet supported. Existing pre-public-preview indexes cannot be backfilled with a schema — to use FTS, dense + FTS, or any document API query in `2026-01.alpha`, create a new index with the desired schema and reindex documents. * **Metadata is auto-indexed**: any field on an upserted document that is not declared in the schema is automatically indexed for filtering. The schema declares only ranking fields (FTS-enabled `string`, `dense_vector`, `sparse_vector`); declaring metadata-only fields (`string` without `full_text_search`, `string_list`, `float`, `boolean`) is rejected at index creation. Track metadata field names and types in your application — Pinecone infers the type from the values you upsert. * **Bulk import** from object storage is supported for indexes with document schemas via JSONL files — see [Bulk import](#bulk-import). Semantic-text (auto-embedded) fields are not yet supported in schemas. * **Maximum results per query**: `top_k` is capped at **10,000**. Full-text search is optimized for ranked retrieval; for aggregation- or count-style queries (e.g., "how many documents contain term X"), faceting is on the roadmap for a future release. * Indexes cannot be created in CMEK-enabled projects. * Backup and restore are not yet supported. * **`describe_index_stats`** is not yet supported on indexes with document schemas. * [Fuzzy matching](#query-syntax-reference) (`term~`, `term~N`) is available only in `query_string` scoring, not in `type: "text"` or in `$match_*` filters. * Single-term prefix wildcards (`auto*`) are not supported; use phrase prefix (`"word auto"*`) instead, or configure a field for [substring search](#substring-search-with-n-grams). ## Pricing Reads and writes on indexes with document schemas are metered using the same [read units (RUs)](/guides/manage-cost/understanding-cost#read-units) and [write units (WUs)](/guides/manage-cost/understanding-cost#write-units) model as vector indexes. List pricing for public preview will be announced before general availability. ## Next steps * **[Create an index](/guides/index-data/create-an-index)**: create an index with a document schema that declares your ranking fields. * **[Model your data](/guides/index-data/data-modeling#schema-patterns)**: schema-pattern recipes for keyword-only, multi-field, dense + FTS, and multi-signal indexes. * **[Choose a search approach](/guides/search/search-overview)**: compare full-text, semantic, sparse-vector, and hybrid search. * **[Hybrid search](/guides/search/hybrid-search)**: combine keyword and vector ranking, including when to use a document schema versus the vector API. * **[Filter by metadata](/guides/search/filter-by-metadata)**: narrow the candidate set before ranking. * **[Understanding cost](/guides/manage-cost/understanding-cost)**: how read units and write units are metered. # Hybrid search Source: https://docs.pinecone.io/guides/search/hybrid-search Combine dense semantic search with sparse lexical search in a single Pinecone query to improve recall for keyword matches, synonyms, and rare terms. [Semantic search](/guides/search/semantic-search) and [lexical search](/guides/search/lexical-search) are powerful information retrieval techniques, but each has notable limitations. For example: * Semantic search can miss results based on exact keyword matches, especially in scenarios involving domain-specific terminology. * Lexical search can miss results based on relationships, such as synonyms and paraphrases. To work around these limitations, you can use hybrid search, which combines semantic and lexical search. This page covers the **vector-API hybrid pattern**: a single index that stores both a dense vector and a sparse vector per record, queried together in one request. For indexes with document schemas, hybrid retrieval is covered in [Full-text search](/guides/search/full-text-search), where one schema declares FTS-enabled `string` (BM25), `dense_vector`, and `sparse_vector` fields side by side and you combine signals with text-match filters or by merging results client-side. For multi-signal indexes that combine dense, sparse, and text fields in a single schema, see the [Multi-signal index pattern](/guides/index-data/data-modeling#schema-patterns). Both patterns are fully supported; pick by data shape (records vs. JSON documents). When you query a single index that stores both dense and sparse vectors, BM25 scores and `pinecone-sparse-english-v0` sparse-weight outputs are **not normalized** to the dense vector range (cosine `[-1, 1]`). Without explicit weighting, the sparse component dominates the combined score. Before going to production, read [Normalize sparse and dense values](#normalize-sparse-and-dense-values) and apply the `hybrid_score_norm` query-time pattern, or model the workload as an [index with a document schema](/guides/get-started/concepts#document) and combine BM25 with a dense or sparse ranking using a text-match filter (or client-side merge) per [Full-text search](/guides/search/full-text-search). ## Choosing a hybrid pattern Pinecone supports three hybrid patterns, split by API surface and data shape. Pick the one that matches your data: | Pattern | API | Data shape | How signals combine | Trade-offs | | ------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | **[Single index for dense and sparse vectors](#use-a-single-index-for-dense-and-sparse-vectors)** | Vector | One record carries both a dense and a sparse vector | Server-side dotproduct of weighted dense + sparse query vectors | Simplest single-request architecture, but BM25/sparse scores are unbounded — requires `alpha` weighting per query. No integrated embedding. | | **[Separate indexes for dense and sparse vectors](#use-separate-indexes-for-dense-and-sparse-vectors)** | Vector | Two indexes, linked by shared `_id` | Two queries, merged client-side (e.g., [RRF](/guides/search/reciprocal-rank-fusion)) | More moving parts, but supports sparse-only queries, integrated embedding, and independent reranking per index. | | **[Multi-field document schema](/guides/search/full-text-search)** | Document | One document with `dense_vector` + FTS-enabled `string` fields in the same schema | Either: dense ranking *narrowed* by a text-match filter (`$match_phrase`/`$match_all`/`$match_any`); or two searches merged client-side | Text-centric workloads; no `alpha` tuning needed. Doesn't support integrated embedding in public preview. | **Rule of thumb:** if your hybrid signal is "I have both vectors per record," reach for a vector-API pattern (single index or separate indexes). If your hybrid signal is "I have text plus an embedding for the same document," reach for the document API (multi-field document schema). The remainder of this page covers the vector-API patterns. For the document API hybrid pattern, see [Full-text search](/guides/search/full-text-search) and the [multi-signal schema example](/guides/index-data/data-modeling#schema-patterns). ## Hybrid search approaches There are two ways to perform hybrid search **on the vector API**: * [Use a single index for dense and sparse vectors](#use-a-single-index-for-dense-and-sparse-vectors). This is the **recommended** approach for most use cases because it provides a simpler architecture with less operational overhead.
Steps: 1. [Create the index](#hybrid-single-1-create) 2. [Generate vectors](#hybrid-single-2-embed) 3. [Upsert records](#hybrid-single-3-upsert) 4. [Search the index](#hybrid-single-4-query) 5. [Search with explicit weighting](#hybrid-single-5-alpha) * [Use separate indexes for dense and sparse vectors](#use-separate-indexes-for-dense-and-sparse-vectors). This approach provides more flexibility but requires managing two indexes and maintaining linkages between vectors.
Steps: 1. [Create the indexes](#hybrid-sep-1-create) 2. [Upsert vectors](#hybrid-sep-2-upsert) 3. [Search by dense vectors](#hybrid-sep-3-dense) 4. [Search by sparse vectors](#hybrid-sep-4-sparse) 5. [Merge and deduplicate](#hybrid-sep-5-merge) 6. [Rerank](#hybrid-sep-6-rerank) The following table summarizes the key differences between the two approaches: | Approach | Pros | Cons | | :------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Single index for both vectors |
  • You make requests to only a single index.
  • The linkage between dense and sparse vectors is implicit.
  • Simpler architecture with less operational overhead.
|
  • You can't do sparse-only queries.
  • You can't use integrated embedding and reranking.
| | Separate indexes per vector type |
  • You can start with dense vectors for semantic search and add sparse vectors for lexical search later.
  • You can do sparse-only queries.
  • You can rerank at multiple levels (for each index and for merged results).
  • You can use integrated embedding and reranking.
|
  • You need to manage and make requests to two separate indexes.
  • You need to maintain the linkage between sparse and dense vectors across indexes.
  • More complex architecture with additional operational overhead.
| ## Choosing the right approach **For most use cases, a single index that stores both dense and sparse vectors is recommended.** * This approach provides a simpler architecture with less operational overhead. You make requests to a single index rather than managing and querying two separate indexes. * The linkage between dense and sparse vectors is implicit, eliminating the need to maintain explicit linkages across indexes. * You can perform hybrid queries with a single request, reducing latency and complexity compared to querying separate indexes and merging results. **Consider using separate indexes only when:** * You need to do sparse-only queries. * You want to use Pinecone's integrated sparse model ([`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0)), which only works with indexes that store sparse vectors. * You need complete independence in reranking results from each index. * You require the flexibility to manage dense and sparse vectors in separate indexes. ## Normalize sparse and dense values A single index that stores both vector types doesn't reconcile their score ranges. The two scoring components have very different shapes: * **Dense vectors** scored with `dotproduct` against unit-norm embeddings produce values roughly in `[-1, 1]` (or close, depending on the embedding model). * **BM25-style sparse weights** and `pinecone-sparse-english-v0` outputs are **unbounded positive** values that scale with term frequency, document length, and vocabulary distribution. Raw scores can run into double digits. Without explicit weighting, the sparse component dominates the combined score. To make the two signals comparable, apply a **convex combination** at query time using an `alpha` parameter: * `combined = alpha * dense + (1 - alpha) * sparse` * `alpha = 1.0` ranks by dense only (pure semantic). * `alpha = 0.0` ranks by sparse only (pure lexical). * `alpha = 0.5` weights the two signals equally. Pinecone applies this weighting by **scaling the query vectors before sending them to the index** (the index itself stores raw values). Use the [`hybrid_score_norm`](#search-the-index-with-explicit-weighting) helper documented in the walkthrough below; it multiplies the dense values by `alpha` and the sparse values by `1 - alpha`, so the underlying dotproduct produces the desired combination. ### Choosing alpha There's no universal best value — alpha depends on your data and query distribution. Reasonable starting points: * **`alpha = 0.75`** (dense-leaning) — good default for natural-language queries on conversational or document-style content. * **`alpha = 0.5`** — balanced; useful when keyword and semantic signals contribute equally (e.g., mixed exact-match and synonym queries). * **`alpha = 0.25`** (sparse-leaning) — good for queries with high keyword specificity (product SKUs, technical IDs, named entities). We recommend evaluating multiple alpha values against a labeled relevance set drawn from your own workload. If your workload is text-centric, an [index with a document schema](/guides/get-started/concepts#document) sidesteps the alpha-tuning step entirely: declare BM25 and vector fields in one schema and pick a ranking signal per query, with no normalization to fit. See [Full-text search](/guides/search/full-text-search). ## Use a single index for dense and sparse vectors To perform hybrid search with a single index that stores both dense and sparse vectors, follow these steps: To store both dense and sparse vectors in a single index, use the [`create_index`](/reference/api/latest/control-plane/create_index) operation, setting the `vector_type` to `dense` and the `metric` to `dotproduct`. This is the only combination that supports dense/sparse search on a single index. ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key="YOUR_API_KEY") index_name = "hybrid-index" if not pc.has_index(index_name): pc.create_index( name=index_name, vector_type="dense", dimension=1024, metric="dotproduct", spec=ServerlessSpec( cloud="aws", region="us-east-1" ) ) ``` Use Pinecone's [hosted embedding models](/guides/index-data/create-an-index#embedding-models) to [convert data into dense and sparse vectors](/reference/api/latest/inference/generate-embeddings). ```python Python [expandable] theme={null} # Define the records data = [ { "_id": "vec1", "chunk_text": "Apple Inc. issued a $10 billion corporate bond in 2023." }, { "_id": "vec2", "chunk_text": "ETFs tracking the S&P 500 outperformed active funds last year." }, { "_id": "vec3", "chunk_text": "Tesla's options volume surged after the latest earnings report." }, { "_id": "vec4", "chunk_text": "Dividend aristocrats are known for consistently raising payouts." }, { "_id": "vec5", "chunk_text": "The Federal Reserve raised interest rates by 0.25% to curb inflation." }, { "_id": "vec6", "chunk_text": "Unemployment hit a record low of 3.7% in Q4 of 2024." }, { "_id": "vec7", "chunk_text": "The CPI index rose by 6% in July 2024, raising concerns about purchasing power." }, { "_id": "vec8", "chunk_text": "GDP growth in emerging markets outpaced developed economies." }, { "_id": "vec9", "chunk_text": "Amazon's acquisition of MGM Studios was valued at $8.45 billion." }, { "_id": "vec10", "chunk_text": "Alphabet reported a 20% increase in advertising revenue." }, { "_id": "vec11", "chunk_text": "ExxonMobil announced a special dividend after record profits." }, { "_id": "vec12", "chunk_text": "Tesla plans a 3-for-1 stock split to attract retail investors." }, { "_id": "vec13", "chunk_text": "Credit card APRs reached an all-time high of 22.8% in 2024." }, { "_id": "vec14", "chunk_text": "A 529 college savings plan offers tax advantages for education." }, { "_id": "vec15", "chunk_text": "Emergency savings should ideally cover 6 months of expenses." }, { "_id": "vec16", "chunk_text": "The average mortgage rate rose to 7.1% in December." }, { "_id": "vec17", "chunk_text": "The SEC fined a hedge fund $50 million for insider trading." }, { "_id": "vec18", "chunk_text": "New ESG regulations require companies to disclose climate risks." }, { "_id": "vec19", "chunk_text": "The IRS introduced a new tax bracket for high earners." }, { "_id": "vec20", "chunk_text": "Compliance with GDPR is mandatory for companies operating in Europe." }, { "_id": "vec21", "chunk_text": "What are the best-performing green bonds in a rising rate environment?" }, { "_id": "vec22", "chunk_text": "How does inflation impact the real yield of Treasury bonds?" }, { "_id": "vec23", "chunk_text": "Top SPAC mergers in the technology sector for 2024." }, { "_id": "vec24", "chunk_text": "Are stablecoins a viable hedge against currency devaluation?" }, { "_id": "vec25", "chunk_text": "Comparison of Roth IRA vs 401(k) for high-income earners." }, { "_id": "vec26", "chunk_text": "Stock splits and their effect on investor sentiment." }, { "_id": "vec27", "chunk_text": "Tech IPOs that disappointed in their first year." }, { "_id": "vec28", "chunk_text": "Impact of interest rate hikes on bank stocks." }, { "_id": "vec29", "chunk_text": "Growth vs. value investing strategies in 2024." }, { "_id": "vec30", "chunk_text": "The role of artificial intelligence in quantitative trading." }, { "_id": "vec31", "chunk_text": "What are the implications of quantitative tightening on equities?" }, { "_id": "vec32", "chunk_text": "How does compounding interest affect long-term investments?" }, { "_id": "vec33", "chunk_text": "What are the best assets to hedge against inflation?" }, { "_id": "vec34", "chunk_text": "Can ETFs provide better diversification than mutual funds?" }, { "_id": "vec35", "chunk_text": "Unemployment hit at 2.4% in Q3 of 2024." }, { "_id": "vec36", "chunk_text": "Unemployment is expected to hit 2.5% in Q3 of 2024." }, { "_id": "vec37", "chunk_text": "In Q3 2025 unemployment for the prior year was revised to 2.2%"}, { "_id": "vec38", "chunk_text": "Emerging markets witnessed increased foreign direct investment as global interest rates stabilized." }, { "_id": "vec39", "chunk_text": "The rise in energy prices significantly impacted inflation trends during the first half of 2024." }, { "_id": "vec40", "chunk_text": "Labor market trends show a declining participation rate despite record low unemployment in 2024." }, { "_id": "vec41", "chunk_text": "Forecasts of global supply chain disruptions eased in late 2024, but consumer prices remained elevated due to persistent demand." }, { "_id": "vec42", "chunk_text": "Tech sector layoffs in Q3 2024 have reshaped hiring trends across high-growth industries." }, { "_id": "vec43", "chunk_text": "The U.S. dollar weakened against a basket of currencies as the global economy adjusted to shifting trade balances." }, { "_id": "vec44", "chunk_text": "Central banks worldwide increased gold reserves to hedge against geopolitical and economic instability." }, { "_id": "vec45", "chunk_text": "Corporate earnings in Q4 2024 were largely impacted by rising raw material costs and currency fluctuations." }, { "_id": "vec46", "chunk_text": "Economic recovery in Q2 2024 relied heavily on government spending in infrastructure and green energy projects." }, { "_id": "vec47", "chunk_text": "The housing market saw a rebound in late 2024, driven by falling mortgage rates and pent-up demand." }, { "_id": "vec48", "chunk_text": "Wage growth outpaced inflation for the first time in years, signaling improved purchasing power in 2024." }, { "_id": "vec49", "chunk_text": "China's economic growth in 2024 slowed to its lowest level in decades due to structural reforms and weak exports." }, { "_id": "vec50", "chunk_text": "AI-driven automation in the manufacturing sector boosted productivity but raised concerns about job displacement." }, { "_id": "vec51", "chunk_text": "The European Union introduced new fiscal policies in 2024 aimed at reducing public debt without stifling growth." }, { "_id": "vec52", "chunk_text": "Record-breaking weather events in early 2024 have highlighted the growing economic impact of climate change." }, { "_id": "vec53", "chunk_text": "Cryptocurrencies faced regulatory scrutiny in 2024, leading to volatility and reduced market capitalization." }, { "_id": "vec54", "chunk_text": "The global tourism sector showed signs of recovery in late 2024 after years of pandemic-related setbacks." }, { "_id": "vec55", "chunk_text": "Trade tensions between the U.S. and China escalated in 2024, impacting global supply chains and investment flows." }, { "_id": "vec56", "chunk_text": "Consumer confidence indices remained resilient in Q2 2024 despite fears of an impending recession." }, { "_id": "vec57", "chunk_text": "Startups in 2024 faced tighter funding conditions as venture capitalists focused on profitability over growth." }, { "_id": "vec58", "chunk_text": "Oil production cuts in Q1 2024 by OPEC nations drove prices higher, influencing global energy policies." }, { "_id": "vec59", "chunk_text": "The adoption of digital currencies by central banks increased in 2024, reshaping monetary policy frameworks." }, { "_id": "vec60", "chunk_text": "Healthcare spending in 2024 surged as governments expanded access to preventive care and pandemic preparedness." }, { "_id": "vec61", "chunk_text": "The World Bank reported declining poverty rates globally, but regional disparities persisted." }, { "_id": "vec62", "chunk_text": "Private equity activity in 2024 focused on renewable energy and technology sectors amid shifting investor priorities." }, { "_id": "vec63", "chunk_text": "Population aging emerged as a critical economic issue in 2024, especially in advanced economies." }, { "_id": "vec64", "chunk_text": "Rising commodity prices in 2024 strained emerging markets dependent on imports of raw materials." }, { "_id": "vec65", "chunk_text": "The global shipping industry experienced declining freight rates in 2024 due to overcapacity and reduced demand." }, { "_id": "vec66", "chunk_text": "Bank lending to small and medium-sized enterprises surged in 2024 as governments incentivized entrepreneurship." }, { "_id": "vec67", "chunk_text": "Renewable energy projects accounted for a record share of global infrastructure investment in 2024." }, { "_id": "vec68", "chunk_text": "Cybersecurity spending reached new highs in 2024, reflecting the growing threat of digital attacks on infrastructure." }, { "_id": "vec69", "chunk_text": "The agricultural sector faced challenges in 2024 due to extreme weather and rising input costs." }, { "_id": "vec70", "chunk_text": "Consumer spending patterns shifted in 2024, with a greater focus on experiences over goods." }, { "_id": "vec71", "chunk_text": "The economic impact of the 2008 financial crisis was mitigated by quantitative easing policies." }, { "_id": "vec72", "chunk_text": "In early 2024, global GDP growth slowed, driven by weaker exports in Asia and Europe." }, { "_id": "vec73", "chunk_text": "The historical relationship between inflation and unemployment is explained by the Phillips Curve." }, { "_id": "vec74", "chunk_text": "The World Trade Organization's role in resolving disputes was tested in 2024." }, { "_id": "vec75", "chunk_text": "The collapse of Silicon Valley Bank raised questions about regulatory oversight in 2024." }, { "_id": "vec76", "chunk_text": "The cost of living crisis has been exacerbated by stagnant wage growth and rising inflation." }, { "_id": "vec77", "chunk_text": "Supply chain resilience became a top priority for multinational corporations in 2024." }, { "_id": "vec78", "chunk_text": "Consumer sentiment surveys in 2024 reflected optimism despite high interest rates." }, { "_id": "vec79", "chunk_text": "The resurgence of industrial policy in Q1 2024 focused on decoupling critical supply chains." }, { "_id": "vec80", "chunk_text": "Technological innovation in the fintech sector disrupted traditional banking in 2024." }, { "_id": "vec81", "chunk_text": "The link between climate change and migration patterns is increasingly recognized." }, { "_id": "vec82", "chunk_text": "Renewable energy subsidies in 2024 reduced the global reliance on fossil fuels." }, { "_id": "vec83", "chunk_text": "The economic fallout of geopolitical tensions was evident in rising defense budgets worldwide." }, { "_id": "vec84", "chunk_text": "The IMF's 2024 global outlook highlighted risks of stagflation in emerging markets." }, { "_id": "vec85", "chunk_text": "Declining birth rates in advanced economies pose long-term challenges for labor markets." }, { "_id": "vec86", "chunk_text": "Digital transformation initiatives in 2024 drove productivity gains in the services sector." }, { "_id": "vec87", "chunk_text": "The U.S. labor market's resilience in 2024 defied predictions of a severe recession." }, { "_id": "vec88", "chunk_text": "New fiscal measures in the European Union aimed to stabilize debt levels post-pandemic." }, { "_id": "vec89", "chunk_text": "Venture capital investments in 2024 leaned heavily toward AI and automation startups." }, { "_id": "vec90", "chunk_text": "The surge in e-commerce in 2024 was facilitated by advancements in logistics technology." }, { "_id": "vec91", "chunk_text": "The impact of ESG investing on corporate strategies has been a major focus in 2024." }, { "_id": "vec92", "chunk_text": "Income inequality widened in 2024 despite strong economic growth in developed nations." }, { "_id": "vec93", "chunk_text": "The collapse of FTX highlighted the volatility and risks associated with cryptocurrencies." }, { "_id": "vec94", "chunk_text": "Cyberattacks targeting financial institutions in 2024 led to record cybersecurity spending." }, { "_id": "vec95", "chunk_text": "Automation in agriculture in 2024 increased yields but displaced rural workers." }, { "_id": "vec96", "chunk_text": "New trade agreements signed 2022 will make an impact in 2024"}, ] ``` ```python Python theme={null} # Convert the chunk_text into dense vectors dense_embeddings = pc.inference.embed( model="llama-text-embed-v2", inputs=[d['chunk_text'] for d in data], parameters={"input_type": "passage", "truncate": "END"} ) # Convert the chunk_text into sparse vectors sparse_embeddings = pc.inference.embed( model="pinecone-sparse-english-v0", inputs=[d['chunk_text'] for d in data], parameters={"input_type": "passage", "truncate": "END"} ) ``` Use the [`upsert`](/reference/api/latest/data-plane/upsert) operation, specifying dense values in the `value` parameter and sparse values in the `sparse_values` parameter. Only indexes that store dense vectors with the [dotproduct distance metric](/guides/index-data/indexing-overview#dotproduct) accept records that also have sparse vectors. Upserting such records into an index with a different distance metric will succeed, but querying will return an error. ```Python Python theme={null} # Target the index # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") # Each record contains an ID, a dense vector, a sparse vector, and the original text as metadata records = [] for d, de, se in zip(data, dense_embeddings, sparse_embeddings): records.append({ "id": d['_id'], "values": de['values'], "sparse_values": {'indices': se['sparse_indices'], 'values': se['sparse_values']}, "metadata": {'text': d['chunk_text']} }) # Upsert the records into the index index.upsert( vectors=records, namespace="example-namespace" ) ``` Use the [`embed`](/reference/api/latest/inference/generate-embeddings) operation to convert your query into a dense vector and a sparse vector, and then use the [`query`](/reference/api/latest/data-plane/query) operation to search the index for the 40 most relevant records. ```Python Python theme={null} query = "Q3 2024 us economic data" # Convert the query into a dense vector dense_query_embedding = pc.inference.embed( model="llama-text-embed-v2", inputs=query, parameters={"input_type": "query", "truncate": "END"} ) # Convert the query into a sparse vector sparse_query_embedding = pc.inference.embed( model="pinecone-sparse-english-v0", inputs=query, parameters={"input_type": "query", "truncate": "END"} ) for d, s in zip(dense_query_embedding, sparse_query_embedding): query_response = index.query( namespace="example-namespace", top_k=40, vector=d['values'], sparse_vector={'indices': s['sparse_indices'], 'values': s['sparse_values']}, include_values=False, include_metadata=True ) print(query_response) ``` ```python Response [expandable] theme={null} {'matches': [{'id': 'vec35', 'metadata': {'text': 'Unemployment hit at 2.4% in Q3 of 2024.'}, 'score': 7.92519569, 'values': []}, {'id': 'vec46', 'metadata': {'text': 'Economic recovery in Q2 2024 relied ' 'heavily on government spending in ' 'infrastructure and green energy projects.'}, 'score': 7.86733627, 'values': []}, {'id': 'vec36', 'metadata': {'text': 'Unemployment is expected to hit 2.5% in Q3 ' 'of 2024.'}, 'score': 7.82636, 'values': []}, {'id': 'vec42', 'metadata': {'text': 'Tech sector layoffs in Q3 2024 have ' 'reshaped hiring trends across high-growth ' 'industries.'}, 'score': 7.79465914, 'values': []}, {'id': 'vec49', 'metadata': {'text': "China's economic growth in 2024 slowed to " 'its lowest level in decades due to ' 'structural reforms and weak exports.'}, 'score': 7.46323156, 'values': []}, {'id': 'vec63', 'metadata': {'text': 'Population aging emerged as a critical ' 'economic issue in 2024, especially in ' 'advanced economies.'}, 'score': 7.29055929, 'values': []}, {'id': 'vec92', 'metadata': {'text': 'Income inequality widened in 2024 despite ' 'strong economic growth in developed ' 'nations.'}, 'score': 6.51210213, 'values': []}, {'id': 'vec52', 'metadata': {'text': 'Record-breaking weather events in early ' '2024 have highlighted the growing economic ' 'impact of climate change.'}, 'score': 6.4125514, 'values': []}, {'id': 'vec62', 'metadata': {'text': 'Private equity activity in 2024 focused on ' 'renewable energy and technology sectors ' 'amid shifting investor priorities.'}, 'score': 4.8084693, 'values': []}, {'id': 'vec89', 'metadata': {'text': 'Venture capital investments in 2024 leaned ' 'heavily toward AI and automation ' 'startups.'}, 'score': 4.7974205, 'values': []}, {'id': 'vec57', 'metadata': {'text': 'Startups in 2024 faced tighter funding ' 'conditions as venture capitalists focused ' 'on profitability over growth.'}, 'score': 4.72518444, 'values': []}, {'id': 'vec37', 'metadata': {'text': 'In Q3 2025 unemployment for the prior year ' 'was revised to 2.2%'}, 'score': 4.71824408, 'values': []}, {'id': 'vec69', 'metadata': {'text': 'The agricultural sector faced challenges ' 'in 2024 due to extreme weather and rising ' 'input costs.'}, 'score': 4.66726208, 'values': []}, {'id': 'vec60', 'metadata': {'text': 'Healthcare spending in 2024 surged as ' 'governments expanded access to preventive ' 'care and pandemic preparedness.'}, 'score': 4.62045908, 'values': []}, {'id': 'vec55', 'metadata': {'text': 'Trade tensions between the U.S. and China ' 'escalated in 2024, impacting global supply ' 'chains and investment flows.'}, 'score': 4.59764862, 'values': []}, {'id': 'vec51', 'metadata': {'text': 'The European Union introduced new fiscal ' 'policies in 2024 aimed at reducing public ' 'debt without stifling growth.'}, 'score': 4.57397079, 'values': []}, {'id': 'vec70', 'metadata': {'text': 'Consumer spending patterns shifted in ' '2024, with a greater focus on experiences ' 'over goods.'}, 'score': 4.55043507, 'values': []}, {'id': 'vec87', 'metadata': {'text': "The U.S. labor market's resilience in 2024 " 'defied predictions of a severe recession.'}, 'score': 4.51785707, 'values': []}, {'id': 'vec90', 'metadata': {'text': 'The surge in e-commerce in 2024 was ' 'facilitated by advancements in logistics ' 'technology.'}, 'score': 4.47754288, 'values': []}, {'id': 'vec78', 'metadata': {'text': 'Consumer sentiment surveys in 2024 ' 'reflected optimism despite high interest ' 'rates.'}, 'score': 4.46246624, 'values': []}, {'id': 'vec53', 'metadata': {'text': 'Cryptocurrencies faced regulatory scrutiny ' 'in 2024, leading to volatility and reduced ' 'market capitalization.'}, 'score': 4.4435873, 'values': []}, {'id': 'vec45', 'metadata': {'text': 'Corporate earnings in Q4 2024 were largely ' 'impacted by rising raw material costs and ' 'currency fluctuations.'}, 'score': 4.43836403, 'values': []}, {'id': 'vec82', 'metadata': {'text': 'Renewable energy subsidies in 2024 reduced ' 'the global reliance on fossil fuels.'}, 'score': 4.43601322, 'values': []}, {'id': 'vec94', 'metadata': {'text': 'Cyberattacks targeting financial ' 'institutions in 2024 led to record ' 'cybersecurity spending.'}, 'score': 4.41334057, 'values': []}, {'id': 'vec47', 'metadata': {'text': 'The housing market saw a rebound in late ' '2024, driven by falling mortgage rates and ' 'pent-up demand.'}, 'score': 4.39900732, 'values': []}, {'id': 'vec41', 'metadata': {'text': 'Forecasts of global supply chain ' 'disruptions eased in late 2024, but ' 'consumer prices remained elevated due to ' 'persistent demand.'}, 'score': 4.37389421, 'values': []}, {'id': 'vec84', 'metadata': {'text': "The IMF's 2024 global outlook highlighted " 'risks of stagflation in emerging markets.'}, 'score': 4.37335157, 'values': []}, {'id': 'vec96', 'metadata': {'text': 'New trade agreements signed 2022 will make ' 'an impact in 2024'}, 'score': 4.33860636, 'values': []}, {'id': 'vec79', 'metadata': {'text': 'The resurgence of industrial policy in Q1 ' '2024 focused on decoupling critical supply ' 'chains.'}, 'score': 4.33784199, 'values': []}, {'id': 'vec6', 'metadata': {'text': 'Unemployment hit a record low of 3.7% in ' 'Q4 of 2024.'}, 'score': 4.33008051, 'values': []}, {'id': 'vec65', 'metadata': {'text': 'The global shipping industry experienced ' 'declining freight rates in 2024 due to ' 'overcapacity and reduced demand.'}, 'score': 4.3228569, 'values': []}, {'id': 'vec64', 'metadata': {'text': 'Rising commodity prices in 2024 strained ' 'emerging markets dependent on imports of ' 'raw materials.'}, 'score': 4.32269621, 'values': []}, {'id': 'vec95', 'metadata': {'text': 'Automation in agriculture in 2024 ' 'increased yields but displaced rural ' 'workers.'}, 'score': 4.31127262, 'values': []}, {'id': 'vec86', 'metadata': {'text': 'Digital transformation initiatives in 2024 ' 'drove productivity gains in the services ' 'sector.'}, 'score': 4.30181122, 'values': []}, {'id': 'vec66', 'metadata': {'text': 'Bank lending to small and medium-sized ' 'enterprises surged in 2024 as governments ' 'incentivized entrepreneurship.'}, 'score': 4.27241945, 'values': []}, {'id': 'vec58', 'metadata': {'text': 'Oil production cuts in Q1 2024 by OPEC ' 'nations drove prices higher, influencing ' 'global energy policies.'}, 'score': 4.21715498, 'values': []}, {'id': 'vec80', 'metadata': {'text': 'Technological innovation in the fintech ' 'sector disrupted traditional banking in ' '2024.'}, 'score': 4.17712116, 'values': []}, {'id': 'vec75', 'metadata': {'text': 'The collapse of Silicon Valley Bank raised ' 'questions about regulatory oversight in ' '2024.'}, 'score': 4.16192341, 'values': []}, {'id': 'vec56', 'metadata': {'text': 'Consumer confidence indices remained ' 'resilient in Q2 2024 despite fears of an ' 'impending recession.'}, 'score': 4.15782213, 'values': []}, {'id': 'vec67', 'metadata': {'text': 'Renewable energy projects accounted for a ' 'record share of global infrastructure ' 'investment in 2024.'}, 'score': 4.14623, 'values': []}], 'namespace': 'example-namespace', 'usage': {'read_units': 9}} ``` For a conceptual overview of why this normalization is needed, see [Normalize sparse and dense values](#normalize-sparse-and-dense-values). Because Pinecone views your sparse-dense vector as a single vector, it does not offer a built-in parameter to adjust the weight of a query's dense part against its sparse part; the index is agnostic to density or sparsity of coordinates in your vectors. You may, however, incorporate a linear weighting scheme by customizing your query vector, as demonstrated in the function below. The following example transforms vector values using an alpha parameter. ```Python Python theme={null} def hybrid_score_norm(dense, sparse, alpha: float): """Hybrid score using a convex combination alpha * dense + (1 - alpha) * sparse Args: dense: Array of floats representing sparse: a dict of `indices` and `values` alpha: scale between 0 and 1 """ if alpha < 0 or alpha > 1: raise ValueError("Alpha must be between 0 and 1") hs = { 'indices': sparse['indices'], 'values': [v * (1 - alpha) for v in sparse['values']] } return [v * alpha for v in dense], hs ``` The following example transforms a vector using the above function, then queries a Pinecone index. ```Python Python theme={null} sparse_vector = { 'indices': [10, 45, 16], 'values': [0.5, 0.5, 0.2] } dense_vector = [0.1, 0.2, 0.3] hdense, hsparse = hybrid_score_norm(dense_vector, sparse_vector, alpha=0.75) query_response = index.query( namespace="example-namespace", top_k=10, vector=hdense, sparse_vector=hsparse ) ``` ## Use separate indexes for dense and sparse vectors To perform hybrid search with separate indexes, follow these steps: [Create one index for dense vectors](/guides/index-data/create-an-index#create-an-index-for-dense-vectors) and [another for sparse vectors](/guides/index-data/create-an-index#create-an-index-for-sparse-vectors), either with integrated embedding or for vectors created with external models. For example, the following code creates indexes with integrated embedding models. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") dense_index_name = "dense-for-hybrid-py" sparse_index_name = "sparse-for-hybrid-py" if not pc.has_index(dense_index_name): pc.create_index_for_model( name=dense_index_name, cloud="aws", region="us-east-1", embed={ "model":"llama-text-embed-v2", "field_map":{"text": "chunk_text"} } ) if not pc.has_index(sparse_index_name): pc.create_index_for_model( name=sparse_index_name, cloud="aws", region="us-east-1", embed={ "model":"pinecone-sparse-english-v0", "field_map":{"text": "chunk_text"} } ) ``` [Upsert dense vectors](/guides/index-data/upsert-data#upsert-dense-vectors) and [upsert sparse vectors](/guides/index-data/upsert-data#upsert-sparse-vectors) into their respective indexes. Make sure to establish a linkage between the dense and sparse vectors so you can merge and deduplicate search results later. For example, the following uses `_id` as the linkage, but you can use any other custom field as well. Because the indexes are integrated with embedding models, you provide the source texts and Pinecone converts them to vectors automatically. ```python Python [expandable] theme={null} # Define the records records = [ { "_id": "vec1", "chunk_text": "Apple Inc. issued a $10 billion corporate bond in 2023." }, { "_id": "vec2", "chunk_text": "ETFs tracking the S&P 500 outperformed active funds last year." }, { "_id": "vec3", "chunk_text": "Tesla's options volume surged after the latest earnings report." }, { "_id": "vec4", "chunk_text": "Dividend aristocrats are known for consistently raising payouts." }, { "_id": "vec5", "chunk_text": "The Federal Reserve raised interest rates by 0.25% to curb inflation." }, { "_id": "vec6", "chunk_text": "Unemployment hit a record low of 3.7% in Q4 of 2024." }, { "_id": "vec7", "chunk_text": "The CPI index rose by 6% in July 2024, raising concerns about purchasing power." }, { "_id": "vec8", "chunk_text": "GDP growth in emerging markets outpaced developed economies." }, { "_id": "vec9", "chunk_text": "Amazon's acquisition of MGM Studios was valued at $8.45 billion." }, { "_id": "vec10", "chunk_text": "Alphabet reported a 20% increase in advertising revenue." }, { "_id": "vec11", "chunk_text": "ExxonMobil announced a special dividend after record profits." }, { "_id": "vec12", "chunk_text": "Tesla plans a 3-for-1 stock split to attract retail investors." }, { "_id": "vec13", "chunk_text": "Credit card APRs reached an all-time high of 22.8% in 2024." }, { "_id": "vec14", "chunk_text": "A 529 college savings plan offers tax advantages for education." }, { "_id": "vec15", "chunk_text": "Emergency savings should ideally cover 6 months of expenses." }, { "_id": "vec16", "chunk_text": "The average mortgage rate rose to 7.1% in December." }, { "_id": "vec17", "chunk_text": "The SEC fined a hedge fund $50 million for insider trading." }, { "_id": "vec18", "chunk_text": "New ESG regulations require companies to disclose climate risks." }, { "_id": "vec19", "chunk_text": "The IRS introduced a new tax bracket for high earners." }, { "_id": "vec20", "chunk_text": "Compliance with GDPR is mandatory for companies operating in Europe." }, { "_id": "vec21", "chunk_text": "What are the best-performing green bonds in a rising rate environment?" }, { "_id": "vec22", "chunk_text": "How does inflation impact the real yield of Treasury bonds?" }, { "_id": "vec23", "chunk_text": "Top SPAC mergers in the technology sector for 2024." }, { "_id": "vec24", "chunk_text": "Are stablecoins a viable hedge against currency devaluation?" }, { "_id": "vec25", "chunk_text": "Comparison of Roth IRA vs 401(k) for high-income earners." }, { "_id": "vec26", "chunk_text": "Stock splits and their effect on investor sentiment." }, { "_id": "vec27", "chunk_text": "Tech IPOs that disappointed in their first year." }, { "_id": "vec28", "chunk_text": "Impact of interest rate hikes on bank stocks." }, { "_id": "vec29", "chunk_text": "Growth vs. value investing strategies in 2024." }, { "_id": "vec30", "chunk_text": "The role of artificial intelligence in quantitative trading." }, { "_id": "vec31", "chunk_text": "What are the implications of quantitative tightening on equities?" }, { "_id": "vec32", "chunk_text": "How does compounding interest affect long-term investments?" }, { "_id": "vec33", "chunk_text": "What are the best assets to hedge against inflation?" }, { "_id": "vec34", "chunk_text": "Can ETFs provide better diversification than mutual funds?" }, { "_id": "vec35", "chunk_text": "Unemployment hit at 2.4% in Q3 of 2024." }, { "_id": "vec36", "chunk_text": "Unemployment is expected to hit 2.5% in Q3 of 2024." }, { "_id": "vec37", "chunk_text": "In Q3 2025 unemployment for the prior year was revised to 2.2%"}, { "_id": "vec38", "chunk_text": "Emerging markets witnessed increased foreign direct investment as global interest rates stabilized." }, { "_id": "vec39", "chunk_text": "The rise in energy prices significantly impacted inflation trends during the first half of 2024." }, { "_id": "vec40", "chunk_text": "Labor market trends show a declining participation rate despite record low unemployment in 2024." }, { "_id": "vec41", "chunk_text": "Forecasts of global supply chain disruptions eased in late 2024, but consumer prices remained elevated due to persistent demand." }, { "_id": "vec42", "chunk_text": "Tech sector layoffs in Q3 2024 have reshaped hiring trends across high-growth industries." }, { "_id": "vec43", "chunk_text": "The U.S. dollar weakened against a basket of currencies as the global economy adjusted to shifting trade balances." }, { "_id": "vec44", "chunk_text": "Central banks worldwide increased gold reserves to hedge against geopolitical and economic instability." }, { "_id": "vec45", "chunk_text": "Corporate earnings in Q4 2024 were largely impacted by rising raw material costs and currency fluctuations." }, { "_id": "vec46", "chunk_text": "Economic recovery in Q2 2024 relied heavily on government spending in infrastructure and green energy projects." }, { "_id": "vec47", "chunk_text": "The housing market saw a rebound in late 2024, driven by falling mortgage rates and pent-up demand." }, { "_id": "vec48", "chunk_text": "Wage growth outpaced inflation for the first time in years, signaling improved purchasing power in 2024." }, { "_id": "vec49", "chunk_text": "China's economic growth in 2024 slowed to its lowest level in decades due to structural reforms and weak exports." }, { "_id": "vec50", "chunk_text": "AI-driven automation in the manufacturing sector boosted productivity but raised concerns about job displacement." }, { "_id": "vec51", "chunk_text": "The European Union introduced new fiscal policies in 2024 aimed at reducing public debt without stifling growth." }, { "_id": "vec52", "chunk_text": "Record-breaking weather events in early 2024 have highlighted the growing economic impact of climate change." }, { "_id": "vec53", "chunk_text": "Cryptocurrencies faced regulatory scrutiny in 2024, leading to volatility and reduced market capitalization." }, { "_id": "vec54", "chunk_text": "The global tourism sector showed signs of recovery in late 2024 after years of pandemic-related setbacks." }, { "_id": "vec55", "chunk_text": "Trade tensions between the U.S. and China escalated in 2024, impacting global supply chains and investment flows." }, { "_id": "vec56", "chunk_text": "Consumer confidence indices remained resilient in Q2 2024 despite fears of an impending recession." }, { "_id": "vec57", "chunk_text": "Startups in 2024 faced tighter funding conditions as venture capitalists focused on profitability over growth." }, { "_id": "vec58", "chunk_text": "Oil production cuts in Q1 2024 by OPEC nations drove prices higher, influencing global energy policies." }, { "_id": "vec59", "chunk_text": "The adoption of digital currencies by central banks increased in 2024, reshaping monetary policy frameworks." }, { "_id": "vec60", "chunk_text": "Healthcare spending in 2024 surged as governments expanded access to preventive care and pandemic preparedness." }, { "_id": "vec61", "chunk_text": "The World Bank reported declining poverty rates globally, but regional disparities persisted." }, { "_id": "vec62", "chunk_text": "Private equity activity in 2024 focused on renewable energy and technology sectors amid shifting investor priorities." }, { "_id": "vec63", "chunk_text": "Population aging emerged as a critical economic issue in 2024, especially in advanced economies." }, { "_id": "vec64", "chunk_text": "Rising commodity prices in 2024 strained emerging markets dependent on imports of raw materials." }, { "_id": "vec65", "chunk_text": "The global shipping industry experienced declining freight rates in 2024 due to overcapacity and reduced demand." }, { "_id": "vec66", "chunk_text": "Bank lending to small and medium-sized enterprises surged in 2024 as governments incentivized entrepreneurship." }, { "_id": "vec67", "chunk_text": "Renewable energy projects accounted for a record share of global infrastructure investment in 2024." }, { "_id": "vec68", "chunk_text": "Cybersecurity spending reached new highs in 2024, reflecting the growing threat of digital attacks on infrastructure." }, { "_id": "vec69", "chunk_text": "The agricultural sector faced challenges in 2024 due to extreme weather and rising input costs." }, { "_id": "vec70", "chunk_text": "Consumer spending patterns shifted in 2024, with a greater focus on experiences over goods." }, { "_id": "vec71", "chunk_text": "The economic impact of the 2008 financial crisis was mitigated by quantitative easing policies." }, { "_id": "vec72", "chunk_text": "In early 2024, global GDP growth slowed, driven by weaker exports in Asia and Europe." }, { "_id": "vec73", "chunk_text": "The historical relationship between inflation and unemployment is explained by the Phillips Curve." }, { "_id": "vec74", "chunk_text": "The World Trade Organization's role in resolving disputes was tested in 2024." }, { "_id": "vec75", "chunk_text": "The collapse of Silicon Valley Bank raised questions about regulatory oversight in 2024." }, { "_id": "vec76", "chunk_text": "The cost of living crisis has been exacerbated by stagnant wage growth and rising inflation." }, { "_id": "vec77", "chunk_text": "Supply chain resilience became a top priority for multinational corporations in 2024." }, { "_id": "vec78", "chunk_text": "Consumer sentiment surveys in 2024 reflected optimism despite high interest rates." }, { "_id": "vec79", "chunk_text": "The resurgence of industrial policy in Q1 2024 focused on decoupling critical supply chains." }, { "_id": "vec80", "chunk_text": "Technological innovation in the fintech sector disrupted traditional banking in 2024." }, { "_id": "vec81", "chunk_text": "The link between climate change and migration patterns is increasingly recognized." }, { "_id": "vec82", "chunk_text": "Renewable energy subsidies in 2024 reduced the global reliance on fossil fuels." }, { "_id": "vec83", "chunk_text": "The economic fallout of geopolitical tensions was evident in rising defense budgets worldwide." }, { "_id": "vec84", "chunk_text": "The IMF's 2024 global outlook highlighted risks of stagflation in emerging markets." }, { "_id": "vec85", "chunk_text": "Declining birth rates in advanced economies pose long-term challenges for labor markets." }, { "_id": "vec86", "chunk_text": "Digital transformation initiatives in 2024 drove productivity gains in the services sector." }, { "_id": "vec87", "chunk_text": "The U.S. labor market's resilience in 2024 defied predictions of a severe recession." }, { "_id": "vec88", "chunk_text": "New fiscal measures in the European Union aimed to stabilize debt levels post-pandemic." }, { "_id": "vec89", "chunk_text": "Venture capital investments in 2024 leaned heavily toward AI and automation startups." }, { "_id": "vec90", "chunk_text": "The surge in e-commerce in 2024 was facilitated by advancements in logistics technology." }, { "_id": "vec91", "chunk_text": "The impact of ESG investing on corporate strategies has been a major focus in 2024." }, { "_id": "vec92", "chunk_text": "Income inequality widened in 2024 despite strong economic growth in developed nations." }, { "_id": "vec93", "chunk_text": "The collapse of FTX highlighted the volatility and risks associated with cryptocurrencies." }, { "_id": "vec94", "chunk_text": "Cyberattacks targeting financial institutions in 2024 led to record cybersecurity spending." }, { "_id": "vec95", "chunk_text": "Automation in agriculture in 2024 increased yields but displaced rural workers." }, { "_id": "vec96", "chunk_text": "New trade agreements signed 2022 will make an impact in 2024"}, ] ``` ```python Python theme={null} # Target both indexes # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index dense_index = pc.Index(host="INDEX_HOST") sparse_index = pc.Index(host="INDEX_HOST") # Upsert the records # The `chunk_text` fields are converted to dense and sparse vectors dense_index.upsert_records("example-namespace", records) sparse_index.upsert_records("example-namespace", records) ``` Perform a [semantic search](/guides/search/semantic-search) against the index that stores dense vectors. For example, the following code searches that index for 40 records most semantically related to the query "Q3 2024 us economic data". Because the index is integrated with an embedding model, you provide the query as text and Pinecone converts the text to a dense vector automatically. ```python Python theme={null} query = "Q3 2024 us economic data" dense_results = dense_index.search( namespace="example-namespace", query={ "top_k": 40, "inputs": { "text": query } } ) print(dense_results) ``` ```python Response [expandable] theme={null} {'result': {'hits': [{'_id': 'vec35', '_score': 0.8629686832427979, 'fields': {'chunk_text': 'Unemployment hit at 2.4% in Q3 ' 'of 2024.'}}, {'_id': 'vec36', '_score': 0.8573639988899231, 'fields': {'chunk_text': 'Unemployment is expected to ' 'hit 2.5% in Q3 of 2024.'}}, {'_id': 'vec6', '_score': 0.8535352945327759, 'fields': {'chunk_text': 'Unemployment hit a record low ' 'of 3.7% in Q4 of 2024.'}}, {'_id': 'vec42', '_score': 0.8336166739463806, 'fields': {'chunk_text': 'Tech sector layoffs in Q3 2024 ' 'have reshaped hiring trends ' 'across high-growth ' 'industries.'}}, {'_id': 'vec48', '_score': 0.8328524827957153, 'fields': {'chunk_text': 'Wage growth outpaced inflation ' 'for the first time in years, ' 'signaling improved purchasing ' 'power in 2024.'}}, {'_id': 'vec55', '_score': 0.8322604298591614, 'fields': {'chunk_text': 'Trade tensions between the ' 'U.S. and China escalated in ' '2024, impacting global supply ' 'chains and investment flows.'}}, {'_id': 'vec45', '_score': 0.8309446573257446, 'fields': {'chunk_text': 'Corporate earnings in Q4 2024 ' 'were largely impacted by ' 'rising raw material costs and ' 'currency fluctuations.'}}, {'_id': 'vec72', '_score': 0.8275909423828125, 'fields': {'chunk_text': 'In early 2024, global GDP ' 'growth slowed, driven by ' 'weaker exports in Asia and ' 'Europe.'}}, {'_id': 'vec29', '_score': 0.8270887136459351, 'fields': {'chunk_text': 'Growth vs. value investing ' 'strategies in 2024.'}}, {'_id': 'vec46', '_score': 0.8263787627220154, 'fields': {'chunk_text': 'Economic recovery in Q2 2024 ' 'relied heavily on government ' 'spending in infrastructure and ' 'green energy projects.'}}, {'_id': 'vec79', '_score': 0.8258304595947266, 'fields': {'chunk_text': 'The resurgence of industrial ' 'policy in Q1 2024 focused on ' 'decoupling critical supply ' 'chains.'}}, {'_id': 'vec87', '_score': 0.8257324695587158, 'fields': {'chunk_text': "The U.S. labor market's " 'resilience in 2024 defied ' 'predictions of a severe ' 'recession.'}}, {'_id': 'vec40', '_score': 0.8253997564315796, 'fields': {'chunk_text': 'Labor market trends show a ' 'declining participation rate ' 'despite record low ' 'unemployment in 2024.'}}, {'_id': 'vec37', '_score': 0.8235862255096436, 'fields': {'chunk_text': 'In Q3 2025 unemployment for ' 'the prior year was revised to ' '2.2%'}}, {'_id': 'vec58', '_score': 0.8233317136764526, 'fields': {'chunk_text': 'Oil production cuts in Q1 2024 ' 'by OPEC nations drove prices ' 'higher, influencing global ' 'energy policies.'}}, {'_id': 'vec47', '_score': 0.8231339454650879, 'fields': {'chunk_text': 'The housing market saw a ' 'rebound in late 2024, driven ' 'by falling mortgage rates and ' 'pent-up demand.'}}, {'_id': 'vec41', '_score': 0.8187897801399231, 'fields': {'chunk_text': 'Forecasts of global supply ' 'chain disruptions eased in ' 'late 2024, but consumer prices ' 'remained elevated due to ' 'persistent demand.'}}, {'_id': 'vec56', '_score': 0.8155254125595093, 'fields': {'chunk_text': 'Consumer confidence indices ' 'remained resilient in Q2 2024 ' 'despite fears of an impending ' 'recession.'}}, {'_id': 'vec63', '_score': 0.8136948347091675, 'fields': {'chunk_text': 'Population aging emerged as a ' 'critical economic issue in ' '2024, especially in advanced ' 'economies.'}}, {'_id': 'vec52', '_score': 0.8129132390022278, 'fields': {'chunk_text': 'Record-breaking weather events ' 'in early 2024 have highlighted ' 'the growing economic impact of ' 'climate change.'}}, {'_id': 'vec23', '_score': 0.8126378655433655, 'fields': {'chunk_text': 'Top SPAC mergers in the ' 'technology sector for 2024.'}}, {'_id': 'vec62', '_score': 0.8116977214813232, 'fields': {'chunk_text': 'Private equity activity in ' '2024 focused on renewable ' 'energy and technology sectors ' 'amid shifting investor ' 'priorities.'}}, {'_id': 'vec64', '_score': 0.8109902739524841, 'fields': {'chunk_text': 'Rising commodity prices in ' '2024 strained emerging markets ' 'dependent on imports of raw ' 'materials.'}}, {'_id': 'vec54', '_score': 0.8092231154441833, 'fields': {'chunk_text': 'The global tourism sector ' 'showed signs of recovery in ' 'late 2024 after years of ' 'pandemic-related setbacks.'}}, {'_id': 'vec96', '_score': 0.8075559735298157, 'fields': {'chunk_text': 'New trade agreements signed ' '2022 will make an impact in ' '2024'}}, {'_id': 'vec49', '_score': 0.8062589764595032, 'fields': {'chunk_text': "China's economic growth in " '2024 slowed to its lowest ' 'level in decades due to ' 'structural reforms and weak ' 'exports.'}}, {'_id': 'vec7', '_score': 0.8034461140632629, 'fields': {'chunk_text': 'The CPI index rose by 6% in ' 'July 2024, raising concerns ' 'about purchasing power.'}}, {'_id': 'vec84', '_score': 0.8027160167694092, 'fields': {'chunk_text': "The IMF's 2024 global outlook " 'highlighted risks of ' 'stagflation in emerging ' 'markets.'}}, {'_id': 'vec13', '_score': 0.8010239601135254, 'fields': {'chunk_text': 'Credit card APRs reached an ' 'all-time high of 22.8% in ' '2024.'}}, {'_id': 'vec53', '_score': 0.8007135391235352, 'fields': {'chunk_text': 'Cryptocurrencies faced ' 'regulatory scrutiny in 2024, ' 'leading to volatility and ' 'reduced market ' 'capitalization.'}}, {'_id': 'vec60', '_score': 0.7980866432189941, 'fields': {'chunk_text': 'Healthcare spending in 2024 ' 'surged as governments expanded ' 'access to preventive care and ' 'pandemic preparedness.'}}, {'_id': 'vec91', '_score': 0.7980680465698242, 'fields': {'chunk_text': 'The impact of ESG investing on ' 'corporate strategies has been ' 'a major focus in 2024.'}}, {'_id': 'vec68', '_score': 0.797269880771637, 'fields': {'chunk_text': 'Cybersecurity spending reached ' 'new highs in 2024, reflecting ' 'the growing threat of digital ' 'attacks on infrastructure.'}}, {'_id': 'vec59', '_score': 0.795337438583374, 'fields': {'chunk_text': 'The adoption of digital ' 'currencies by central banks ' 'increased in 2024, reshaping ' 'monetary policy frameworks.'}}, {'_id': 'vec39', '_score': 0.793889045715332, 'fields': {'chunk_text': 'The rise in energy prices ' 'significantly impacted ' 'inflation trends during the ' 'first half of 2024.'}}, {'_id': 'vec66', '_score': 0.7919396162033081, 'fields': {'chunk_text': 'Bank lending to small and ' 'medium-sized enterprises ' 'surged in 2024 as governments ' 'incentivized ' 'entrepreneurship.'}}, {'_id': 'vec57', '_score': 0.7917722463607788, 'fields': {'chunk_text': 'Startups in 2024 faced tighter ' 'funding conditions as venture ' 'capitalists focused on ' 'profitability over growth.'}}, {'_id': 'vec75', '_score': 0.7907494306564331, 'fields': {'chunk_text': 'The collapse of Silicon Valley ' 'Bank raised questions about ' 'regulatory oversight in ' '2024.'}}, {'_id': 'vec51', '_score': 0.790622889995575, 'fields': {'chunk_text': 'The European Union introduced ' 'new fiscal policies in 2024 ' 'aimed at reducing public debt ' 'without stifling growth.'}}, {'_id': 'vec89', '_score': 0.7899052500724792, 'fields': {'chunk_text': 'Venture capital investments in ' '2024 leaned heavily toward AI ' 'and automation startups.'}}]}, 'usage': {'embed_total_tokens': 12, 'read_units': 1}} ``` Perform a [lexical search](/guides/search/lexical-search) against the index that stores sparse vectors. For example, the following code searches that index for 40 records that most exactly match the words in the query. Again, because the index is integrated with an embedding model, you provide the query as text and Pinecone converts the text to a sparse vector automatically. ```python Python theme={null} sparse_results = sparse_index.search( namespace="example-namespace", query={ "top_k": 40, "inputs": { "text": query } } ) print(sparse_results) ``` ```python Response [expandable] theme={null} {'result': {'hits': [{'_id': 'vec35', '_score': 7.0625, 'fields': {'chunk_text': 'Unemployment hit at 2.4% in Q3 ' 'of 2024.'}}, {'_id': 'vec46', '_score': 7.041015625, 'fields': {'chunk_text': 'Economic recovery in Q2 2024 ' 'relied heavily on government ' 'spending in infrastructure and ' 'green energy projects.'}}, {'_id': 'vec36', '_score': 6.96875, 'fields': {'chunk_text': 'Unemployment is expected to ' 'hit 2.5% in Q3 of 2024.'}}, {'_id': 'vec42', '_score': 6.9609375, 'fields': {'chunk_text': 'Tech sector layoffs in Q3 2024 ' 'have reshaped hiring trends ' 'across high-growth ' 'industries.'}}, {'_id': 'vec49', '_score': 6.65625, 'fields': {'chunk_text': "China's economic growth in " '2024 slowed to its lowest ' 'level in decades due to ' 'structural reforms and weak ' 'exports.'}}, {'_id': 'vec63', '_score': 6.4765625, 'fields': {'chunk_text': 'Population aging emerged as a ' 'critical economic issue in ' '2024, especially in advanced ' 'economies.'}}, {'_id': 'vec92', '_score': 5.72265625, 'fields': {'chunk_text': 'Income inequality widened in ' '2024 despite strong economic ' 'growth in developed nations.'}}, {'_id': 'vec52', '_score': 5.599609375, 'fields': {'chunk_text': 'Record-breaking weather events ' 'in early 2024 have highlighted ' 'the growing economic impact of ' 'climate change.'}}, {'_id': 'vec89', '_score': 4.0078125, 'fields': {'chunk_text': 'Venture capital investments in ' '2024 leaned heavily toward AI ' 'and automation startups.'}}, {'_id': 'vec62', '_score': 3.99609375, 'fields': {'chunk_text': 'Private equity activity in ' '2024 focused on renewable ' 'energy and technology sectors ' 'amid shifting investor ' 'priorities.'}}, {'_id': 'vec57', '_score': 3.93359375, 'fields': {'chunk_text': 'Startups in 2024 faced tighter ' 'funding conditions as venture ' 'capitalists focused on ' 'profitability over growth.'}}, {'_id': 'vec69', '_score': 3.8984375, 'fields': {'chunk_text': 'The agricultural sector faced ' 'challenges in 2024 due to ' 'extreme weather and rising ' 'input costs.'}}, {'_id': 'vec37', '_score': 3.89453125, 'fields': {'chunk_text': 'In Q3 2025 unemployment for ' 'the prior year was revised to ' '2.2%'}}, {'_id': 'vec60', '_score': 3.822265625, 'fields': {'chunk_text': 'Healthcare spending in 2024 ' 'surged as governments expanded ' 'access to preventive care and ' 'pandemic preparedness.'}}, {'_id': 'vec51', '_score': 3.783203125, 'fields': {'chunk_text': 'The European Union introduced ' 'new fiscal policies in 2024 ' 'aimed at reducing public debt ' 'without stifling growth.'}}, {'_id': 'vec55', '_score': 3.765625, 'fields': {'chunk_text': 'Trade tensions between the ' 'U.S. and China escalated in ' '2024, impacting global supply ' 'chains and investment flows.'}}, {'_id': 'vec70', '_score': 3.76171875, 'fields': {'chunk_text': 'Consumer spending patterns ' 'shifted in 2024, with a ' 'greater focus on experiences ' 'over goods.'}}, {'_id': 'vec90', '_score': 3.70703125, 'fields': {'chunk_text': 'The surge in e-commerce in ' '2024 was facilitated by ' 'advancements in logistics ' 'technology.'}}, {'_id': 'vec87', '_score': 3.69140625, 'fields': {'chunk_text': "The U.S. labor market's " 'resilience in 2024 defied ' 'predictions of a severe ' 'recession.'}}, {'_id': 'vec78', '_score': 3.673828125, 'fields': {'chunk_text': 'Consumer sentiment surveys in ' '2024 reflected optimism ' 'despite high interest rates.'}}, {'_id': 'vec82', '_score': 3.66015625, 'fields': {'chunk_text': 'Renewable energy subsidies in ' '2024 reduced the global ' 'reliance on fossil fuels.'}}, {'_id': 'vec53', '_score': 3.642578125, 'fields': {'chunk_text': 'Cryptocurrencies faced ' 'regulatory scrutiny in 2024, ' 'leading to volatility and ' 'reduced market ' 'capitalization.'}}, {'_id': 'vec94', '_score': 3.625, 'fields': {'chunk_text': 'Cyberattacks targeting ' 'financial institutions in 2024 ' 'led to record cybersecurity ' 'spending.'}}, {'_id': 'vec45', '_score': 3.607421875, 'fields': {'chunk_text': 'Corporate earnings in Q4 2024 ' 'were largely impacted by ' 'rising raw material costs and ' 'currency fluctuations.'}}, {'_id': 'vec47', '_score': 3.576171875, 'fields': {'chunk_text': 'The housing market saw a ' 'rebound in late 2024, driven ' 'by falling mortgage rates and ' 'pent-up demand.'}}, {'_id': 'vec84', '_score': 3.5703125, 'fields': {'chunk_text': "The IMF's 2024 global outlook " 'highlighted risks of ' 'stagflation in emerging ' 'markets.'}}, {'_id': 'vec41', '_score': 3.5546875, 'fields': {'chunk_text': 'Forecasts of global supply ' 'chain disruptions eased in ' 'late 2024, but consumer prices ' 'remained elevated due to ' 'persistent demand.'}}, {'_id': 'vec65', '_score': 3.537109375, 'fields': {'chunk_text': 'The global shipping industry ' 'experienced declining freight ' 'rates in 2024 due to ' 'overcapacity and reduced ' 'demand.'}}, {'_id': 'vec96', '_score': 3.53125, 'fields': {'chunk_text': 'New trade agreements signed ' '2022 will make an impact in ' '2024'}}, {'_id': 'vec86', '_score': 3.52734375, 'fields': {'chunk_text': 'Digital transformation ' 'initiatives in 2024 drove ' 'productivity gains in the ' 'services sector.'}}, {'_id': 'vec95', '_score': 3.5234375, 'fields': {'chunk_text': 'Automation in agriculture in ' '2024 increased yields but ' 'displaced rural workers.'}}, {'_id': 'vec64', '_score': 3.51171875, 'fields': {'chunk_text': 'Rising commodity prices in ' '2024 strained emerging markets ' 'dependent on imports of raw ' 'materials.'}}, {'_id': 'vec79', '_score': 3.51171875, 'fields': {'chunk_text': 'The resurgence of industrial ' 'policy in Q1 2024 focused on ' 'decoupling critical supply ' 'chains.'}}, {'_id': 'vec66', '_score': 3.48046875, 'fields': {'chunk_text': 'Bank lending to small and ' 'medium-sized enterprises ' 'surged in 2024 as governments ' 'incentivized ' 'entrepreneurship.'}}, {'_id': 'vec6', '_score': 3.4765625, 'fields': {'chunk_text': 'Unemployment hit a record low ' 'of 3.7% in Q4 of 2024.'}}, {'_id': 'vec58', '_score': 3.39453125, 'fields': {'chunk_text': 'Oil production cuts in Q1 2024 ' 'by OPEC nations drove prices ' 'higher, influencing global ' 'energy policies.'}}, {'_id': 'vec80', '_score': 3.390625, 'fields': {'chunk_text': 'Technological innovation in ' 'the fintech sector disrupted ' 'traditional banking in 2024.'}}, {'_id': 'vec75', '_score': 3.37109375, 'fields': {'chunk_text': 'The collapse of Silicon Valley ' 'Bank raised questions about ' 'regulatory oversight in ' '2024.'}}, {'_id': 'vec67', '_score': 3.357421875, 'fields': {'chunk_text': 'Renewable energy projects ' 'accounted for a record share ' 'of global infrastructure ' 'investment in 2024.'}}, {'_id': 'vec56', '_score': 3.341796875, 'fields': {'chunk_text': 'Consumer confidence indices ' 'remained resilient in Q2 2024 ' 'despite fears of an impending ' 'recession.'}}]}, 'usage': {'embed_total_tokens': 9, 'read_units': 1}} ``` Merge the 40 dense and 40 sparse results and deduplicated them based on the field you used to link sparse and dense vectors. For example, the following code merges and deduplicates the results based on the `_id` field, resulting in 52 unique results. ```python Python theme={null} def merge_chunks(h1, h2): """Get the unique hits from two search results and return them as single array of {'_id', 'chunk_text'} dicts, printing each dict on a new line.""" # Deduplicate by _id deduped_hits = {hit['_id']: hit for hit in h1['result']['hits'] + h2['result']['hits']}.values() # Sort by _score descending sorted_hits = sorted(deduped_hits, key=lambda x: x['_score'], reverse=True) # Transform to format for reranking result = [{'_id': hit['_id'], 'chunk_text': hit['fields']['chunk_text']} for hit in sorted_hits] return result merged_results = merge_chunks(sparse_results, dense_results) print('[\n ' + ',\n '.join(str(obj) for obj in merged_results) + '\n]') ``` ```console Response [expandable] theme={null} [ {'_id': 'vec92', 'chunk_text': 'Income inequality widened in 2024 despite strong economic growth in developed nations.'}, {'_id': 'vec69', 'chunk_text': 'The agricultural sector faced challenges in 2024 due to extreme weather and rising input costs.'}, {'_id': 'vec70', 'chunk_text': 'Consumer spending patterns shifted in 2024, with a greater focus on experiences over goods.'}, {'_id': 'vec90', 'chunk_text': 'The surge in e-commerce in 2024 was facilitated by advancements in logistics technology.'}, {'_id': 'vec78', 'chunk_text': 'Consumer sentiment surveys in 2024 reflected optimism despite high interest rates.'}, {'_id': 'vec82', 'chunk_text': 'Renewable energy subsidies in 2024 reduced the global reliance on fossil fuels.'}, {'_id': 'vec94', 'chunk_text': 'Cyberattacks targeting financial institutions in 2024 led to record cybersecurity spending.'}, {'_id': 'vec65', 'chunk_text': 'The global shipping industry experienced declining freight rates in 2024 due to overcapacity and reduced demand.'}, {'_id': 'vec86', 'chunk_text': 'Digital transformation initiatives in 2024 drove productivity gains in the services sector.'}, {'_id': 'vec95', 'chunk_text': 'Automation in agriculture in 2024 increased yields but displaced rural workers.'}, {'_id': 'vec80', 'chunk_text': 'Technological innovation in the fintech sector disrupted traditional banking in 2024.'}, {'_id': 'vec67', 'chunk_text': 'Renewable energy projects accounted for a record share of global infrastructure investment in 2024.'}, {'_id': 'vec35', 'chunk_text': 'Unemployment hit at 2.4% in Q3 of 2024.'}, {'_id': 'vec36', 'chunk_text': 'Unemployment is expected to hit 2.5% in Q3 of 2024.'}, {'_id': 'vec6', 'chunk_text': 'Unemployment hit a record low of 3.7% in Q4 of 2024.'}, {'_id': 'vec42', 'chunk_text': 'Tech sector layoffs in Q3 2024 have reshaped hiring trends across high-growth industries.'}, {'_id': 'vec48', 'chunk_text': 'Wage growth outpaced inflation for the first time in years, signaling improved purchasing power in 2024.'}, {'_id': 'vec55', 'chunk_text': 'Trade tensions between the U.S. and China escalated in 2024, impacting global supply chains and investment flows.'}, {'_id': 'vec45', 'chunk_text': 'Corporate earnings in Q4 2024 were largely impacted by rising raw material costs and currency fluctuations.'}, {'_id': 'vec72', 'chunk_text': 'In early 2024, global GDP growth slowed, driven by weaker exports in Asia and Europe.'}, {'_id': 'vec29', 'chunk_text': 'Growth vs. value investing strategies in 2024.'}, {'_id': 'vec46', 'chunk_text': 'Economic recovery in Q2 2024 relied heavily on government spending in infrastructure and green energy projects.'}, {'_id': 'vec79', 'chunk_text': 'The resurgence of industrial policy in Q1 2024 focused on decoupling critical supply chains.'}, {'_id': 'vec87', 'chunk_text': "The U.S. labor market's resilience in 2024 defied predictions of a severe recession."}, {'_id': 'vec40', 'chunk_text': 'Labor market trends show a declining participation rate despite record low unemployment in 2024.'}, {'_id': 'vec37', 'chunk_text': 'In Q3 2025 unemployment for the prior year was revised to 2.2%'}, {'_id': 'vec58', 'chunk_text': 'Oil production cuts in Q1 2024 by OPEC nations drove prices higher, influencing global energy policies.'}, {'_id': 'vec47', 'chunk_text': 'The housing market saw a rebound in late 2024, driven by falling mortgage rates and pent-up demand.'}, {'_id': 'vec41', 'chunk_text': 'Forecasts of global supply chain disruptions eased in late 2024, but consumer prices remained elevated due to persistent demand.'}, {'_id': 'vec56', 'chunk_text': 'Consumer confidence indices remained resilient in Q2 2024 despite fears of an impending recession.'}, {'_id': 'vec63', 'chunk_text': 'Population aging emerged as a critical economic issue in 2024, especially in advanced economies.'}, {'_id': 'vec52', 'chunk_text': 'Record-breaking weather events in early 2024 have highlighted the growing economic impact of climate change.'}, {'_id': 'vec23', 'chunk_text': 'Top SPAC mergers in the technology sector for 2024.'}, {'_id': 'vec62', 'chunk_text': 'Private equity activity in 2024 focused on renewable energy and technology sectors amid shifting investor priorities.'}, {'_id': 'vec64', 'chunk_text': 'Rising commodity prices in 2024 strained emerging markets dependent on imports of raw materials.'}, {'_id': 'vec54', 'chunk_text': 'The global tourism sector showed signs of recovery in late 2024 after years of pandemic-related setbacks.'}, {'_id': 'vec96', 'chunk_text': 'New trade agreements signed 2022 will make an impact in 2024'}, {'_id': 'vec49', 'chunk_text': "China's economic growth in 2024 slowed to its lowest level in decades due to structural reforms and weak exports."}, {'_id': 'vec7', 'chunk_text': 'The CPI index rose by 6% in July 2024, raising concerns about purchasing power.'}, {'_id': 'vec84', 'chunk_text': "The IMF's 2024 global outlook highlighted risks of stagflation in emerging markets."}, {'_id': 'vec13', 'chunk_text': 'Credit card APRs reached an all-time high of 22.8% in 2024.'}, {'_id': 'vec53', 'chunk_text': 'Cryptocurrencies faced regulatory scrutiny in 2024, leading to volatility and reduced market capitalization.'}, {'_id': 'vec60', 'chunk_text': 'Healthcare spending in 2024 surged as governments expanded access to preventive care and pandemic preparedness.'}, {'_id': 'vec91', 'chunk_text': 'The impact of ESG investing on corporate strategies has been a major focus in 2024.'}, {'_id': 'vec68', 'chunk_text': 'Cybersecurity spending reached new highs in 2024, reflecting the growing threat of digital attacks on infrastructure.'}, {'_id': 'vec59', 'chunk_text': 'The adoption of digital currencies by central banks increased in 2024, reshaping monetary policy frameworks.'}, {'_id': 'vec39', 'chunk_text': 'The rise in energy prices significantly impacted inflation trends during the first half of 2024.'}, {'_id': 'vec66', 'chunk_text': 'Bank lending to small and medium-sized enterprises surged in 2024 as governments incentivized entrepreneurship.'}, {'_id': 'vec57', 'chunk_text': 'Startups in 2024 faced tighter funding conditions as venture capitalists focused on profitability over growth.'}, {'_id': 'vec75', 'chunk_text': 'The collapse of Silicon Valley Bank raised questions about regulatory oversight in 2024.'}, {'_id': 'vec51', 'chunk_text': 'The European Union introduced new fiscal policies in 2024 aimed at reducing public debt without stifling growth.'}, {'_id': 'vec89', 'chunk_text': 'Venture capital investments in 2024 leaned heavily toward AI and automation startups.'} ] ``` Use one of Pinecone's [hosted reranking models](/guides/search/rerank-results#reranking-models) to rerank the merged and deduplicated results based on a unified relevance score and then return a smaller set of the most highly relevant results. For example, the following code sends the 52 unique results from the last step to the `bge-reranker-v2-m3` reranking model and returns the top 10 most relevant results. ```python Python theme={null} result = pc.inference.rerank( model="bge-reranker-v2-m3", query=query, documents=merged_results, rank_fields=["chunk_text"], top_n=10, return_documents=True, parameters={ "truncate": "END" } ) print("Query", query) print('-----') for row in result.data: print(f"{row['document']['_id']} - {round(row['score'], 2)} - {row['document']['chunk_text']}") ``` ```console Response [expandable] theme={null} Query Q3 2024 us economic data ----- vec36 - 0.84 - Unemployment is expected to hit 2.5% in Q3 of 2024. vec35 - 0.76 - Unemployment hit at 2.4% in Q3 of 2024. vec48 - 0.33 - Wage growth outpaced inflation for the first time in years, signaling improved purchasing power in 2024. vec37 - 0.25 - In Q3 2025 unemployment for the prior year was revised to 2.2% vec42 - 0.21 - Tech sector layoffs in Q3 2024 have reshaped hiring trends across high-growth industries. vec87 - 0.2 - The U.S. labor market's resilience in 2024 defied predictions of a severe recession. vec63 - 0.08 - Population aging emerged as a critical economic issue in 2024, especially in advanced economies. vec92 - 0.08 - Income inequality widened in 2024 despite strong economic growth in developed nations. vec72 - 0.07 - In early 2024, global GDP growth slowed, driven by weaker exports in Asia and Europe. vec46 - 0.06 - Economic recovery in Q2 2024 relied heavily on government spending in infrastructure and green energy projects. ``` # Lexical search Source: https://docs.pinecone.io/guides/search/lexical-search Run sparse-vector lexical search in Pinecone with custom sparse encoders like pinecone-sparse-english-v0 for token-weighted keyword retrieval. This page shows you how to search an [index with sparse vectors](/guides/index-data/indexing-overview#sparse-indexes) for records that most exactly match the words or phrases in a query. This is often called sparse-vector lexical search. For general-purpose text retrieval (product search, content discovery, document Q\&A), we recommend [full-text search](/guides/search/full-text-search). 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 lexical search (this page) is a distinct retrieval mode. Reach for it when your retrieval target is a token-weighted signal you already produce upstream of Pinecone, for example, when you're using a custom sparse encoder such as [`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0), or when your application owns the sparse-vector representation directly. Lexical 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 records scored highest. ## Search with text Searching with text is supported only for [indexes with integrated embedding](/guides/index-data/indexing-overview#integrated-embedding). To search an index of sparse vectors with a query text, use the [`search_records`](/reference/api/latest/data-plane/search_records) operation with the following parameters: * `namespace`: The [namespace](/guides/index-data/indexing-overview#namespaces) to query. To use the default namespace, set to `"__default__"`. * `query.inputs.text`: The query text. Pinecone uses the [embedding model](/guides/index-data/create-an-index#embedding-models) integrated with the index to convert the text to a sparse vector automatically. * `query.top_k`: The number of records to return. * `query.match_terms`: (Optional) A list of terms that must be present in each search result. For more details, see [Filter by required terms](#filter-by-required-terms). * `fields`: (Optional) The fields to return in the response. If not specified, the response includes all fields. For example, the following code converts the query “What is AAPL's outlook, considering both product launches and market conditions?” to a sparse vector and then searches for the 3 most similar vectors in the `example-namespace` namespace: ```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/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") results = index.search( namespace="example-namespace", query={ "inputs": {"text": "What is AAPL's outlook, considering both product launches and market conditions?"}, "top_k": 3 }, fields=["chunk_text", "quarter"] ) print(results) ``` ```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/manage-data/target-an-index const namespace = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace"); const response = await namespace.searchRecords({ query: { topK: 3, inputs: { text: "What is AAPL's outlook, considering both product launches and market conditions?" }, }, fields: ['chunk_text', 'quarter'] }); console.log(response); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import org.openapitools.db_data.client.ApiException; import org.openapitools.db_data.client.model.SearchRecordsResponse; import java.util.*; public class SearchText { public static void main(String[] args) throws ApiException { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "integrated-sparse-java"); String query = "What is AAPL's outlook, considering both product launches and market conditions?"; List fields = new ArrayList<>(); fields.add("category"); fields.add("chunk_text"); // Search the index SearchRecordsResponse recordsResponse = index.searchRecordsByText(query, "example-namespace", fields, 3, null, null); // Print the results System.out.println(recordsResponse); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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/manage-data/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) } res, err := idxConnection.SearchRecords(ctx, &pinecone.SearchRecordsRequest{ Query: pinecone.SearchRecordsQuery{ TopK: 3, Inputs: &map[string]interface{}{ "text": "What is AAPL's outlook, considering both product launches and market conditions?", }, }, Fields: &[]string{"chunk_text", "category"}, }) if err != nil { log.Fatalf("Failed to search records: %v", err) } fmt.Printf(prettifyStruct(res)) } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/records/namespaces/example-namespace/search" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "query": { "inputs": { "text": "What is AAPL'\''s outlook, considering both product launches and market conditions?" }, "top_k": 3 }, "fields": ["chunk_text", "quarter"] }' ``` The results will look as follows. The most similar records are scored highest. ```python Python theme={null} {'result': {'hits': [{'_id': 'vec2', '_score': 10.77734375, 'fields': {'chunk_text': "Analysts suggest that AAPL'''s " 'upcoming Q4 product launch ' 'event might solidify its ' 'position in the premium ' 'smartphone market.', 'quarter': 'Q4'}}, {'_id': 'vec3', '_score': 6.49066162109375, 'fields': {'chunk_text': "AAPL'''s strategic Q3 " 'partnerships with ' 'semiconductor suppliers could ' 'mitigate component risks and ' 'stabilize iPhone production.', 'quarter': 'Q3'}}, {'_id': 'vec1', '_score': 5.3671875, 'fields': {'chunk_text': 'AAPL reported a year-over-year ' 'revenue increase, expecting ' 'stronger Q3 demand for its ' 'flagship phones.', 'quarter': 'Q3'}}]}, 'usage': {'embed_total_tokens': 18, 'read_units': 1}} ``` ```javascript JavaScript theme={null} { result: { hits: [ { _id: "vec2", _score: 10.82421875, fields: { chunk_text: "Analysts suggest that AAPL'''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", quarter: "Q4" } }, { _id: "vec3", _score: 6.49066162109375, fields: { chunk_text: "AAPL'''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.", quarter: "Q3" } }, { _id: "vec1", _score: 5.3671875, fields: { chunk_text: "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", quarter: "Q3" } } ] }, usage: { readUnits: 1, embedTotalTokens: 18 } } ``` ```java Java theme={null} class SearchRecordsResponse { result: class SearchRecordsResponseResult { hits: [class Hit { id: vec2 score: 10.82421875 fields: {chunk_text=Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market., quarter=Q4} additionalProperties: null }, class Hit { id: vec3 score: 6.49066162109375 fields: {chunk_text=AAAPL'''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production., quarter=Q3} additionalProperties: null }, class Hit { id: vec1 score: 5.3671875 fields: {chunk_text=AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones., quarter=Q3} additionalProperties: null }] additionalProperties: null } usage: class SearchUsage { readUnits: 1 embedTotalTokens: 18 } additionalProperties: null } ``` ```go Go theme={null} { "result": { "hits": [ { "_id": "vec2", "_score": 10.833984, "fields": { "chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "quarter": "Q4" } }, { "_id": "vec3", "_score": 6.473572, "fields": { "chunk_text": "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.", "quarter": "Q3" } }, { "_id": "vec1", "_score": 5.3710938, "fields": { "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "quarter": "Q3" } } ] }, "usage": { "read_units": 6, "embed_total_tokens": 18 } } ``` ```json curl theme={null} { "result": { "hits": [ { "_id": "vec2", "_score": 10.82421875, "fields": { "chunk_text": "Analysts suggest that AAPL'''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "quarter": "Q4" } }, { "_id": "vec3", "_score": 6.49066162109375, "fields": { "chunk_text": "AAPL'''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.", "quarter": "Q3" } }, { "_id": "vec1", "_score": 5.3671875, "fields": { "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "quarter": "Q3" } } ] }, "usage": { "embed_total_tokens": 18, "read_units": 1 } } ``` ## Search with a sparse vector To search an index of sparse vectors with a sparse vector representation of a query, use the [`query`](/reference/api/latest/data-plane/query) operation with the following parameters: * `namespace`: The [namespace](/guides/index-data/indexing-overview#namespaces) to query. To use the default namespace, set to `"__default__"`. * `sparse_vector`: The sparse vector values and indices. * `top_k`: The number of results to return. * `include_values`: Whether to include the vector values of the matching records in the response. Defaults to `false`. * `include_metadata`: Whether to include the metadata of the matching records in the response. Defaults to `false`. When querying with `top_k` over 1000, for optimal performance set `include_values=false` and `include_metadata=false` to return only IDs and scores. Since vectors values are retrieved from object storage, include them in your query results only when you need them (especially with higher `top_k` values). For details, see [Decrease latency](/guides/optimize/decrease-latency#avoid-including-vector-values-when-not-needed). For example, the following code uses a sparse vector representation of the query "What is AAPL's outlook, considering both product launches and market conditions?" to search for the 3 most similar vectors in the `example-namespace` namespace: ```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/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") results = index.query( namespace="example-namespace", sparse_vector={ "values": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0], "indices": [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697] }, top_k=3, include_metadata=True, include_values=False ) print(results) ``` ```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/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const queryResponse = await index.namespace('example-namespace').query({ sparseVector: { indices: [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697], values: [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0] }, topK: 3, includeValues: false, includeMetadata: true }); console.log(queryResponse); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices; import io.pinecone.clients.Index; import java.util.*; public class SearchSparseIndex { public static void main(String[] args) throws InterruptedException { // Instantiate Pinecone class Pinecone pinecone = new Pinecone.Builder("YOUR_API_KEY").build(); String indexName = "docs-example"; Index index = pinecone.getIndexConnection(indexName); List sparseIndices = Arrays.asList( 767227209L, 1640781426L, 1690623792L, 2021799277L, 2152645940L, 2295025838L, 2443437770L, 2779594451L, 2956155693L, 3476647774L, 3818127854L, 428309169L); List sparseValues = Arrays.asList( 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f); QueryResponseWithUnsignedIndices queryResponse = index.query(3, null, sparseIndices, sparseValues, null, "example-namespace", null, false, true); System.out.println(queryResponse); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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/manage-data/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) } sparseValues := pinecone.SparseValues{ Indices: []uint32{767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697}, Values: []float32{1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0}, } res, err := idxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{ SparseValues: &sparseValues, TopK: 3, IncludeValues: false, IncludeMetadata: true, }) if err != nil { log.Fatalf("Error encountered when querying by vector: %v", err) } else { fmt.Printf(prettifyStruct(res)) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/query" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "sparseVector": { "values": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0], "indices": [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697] }, "namespace": "example-namespace", "topK": 4, "includeMetadata": true, "includeValues": false }' ``` The results will look as follows. The most similar records are scored highest. ```python Python theme={null} {'matches': [{'id': 'vec2', 'metadata': {'category': 'technology', 'quarter': 'Q4', 'chunk_text': "Analysts suggest that AAPL'''s " 'upcoming Q4 product launch event ' 'might solidify its position in the ' 'premium smartphone market.'}, 'score': 10.9042969, 'values': []}, {'id': 'vec3', 'metadata': {'category': 'technology', 'quarter': 'Q3', 'chunk_text': "AAPL'''s strategic Q3 partnerships " 'with semiconductor suppliers could ' 'mitigate component risks and ' 'stabilize iPhone production'}, 'score': 6.48010254, 'values': []}, {'id': 'vec1', 'metadata': {'category': 'technology', 'quarter': 'Q3', 'chunk_text': 'AAPL reported a year-over-year ' 'revenue increase, expecting ' 'stronger Q3 demand for its flagship ' 'phones.'}, 'score': 5.3671875, 'values': []}], 'namespace': 'example-namespace', 'usage': {'read_units': 1}} ``` ```javascript JavaScript theme={null} { matches: [ { id: 'vec2', score: 10.9042969, values: [], metadata: { chunk_text: "Analysts suggest that AAPL'''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", category: 'technology', quarter: 'Q4' } }, { id: 'vec3', score: 6.48010254, values: [], metadata: { chunk_text: "AAPL'''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.", category: 'technology', quarter: 'Q3' } }, { id: 'vec1', score: 5.3671875, values: [], metadata: { chunk_text: 'AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.', category: 'technology', quarter: 'Q3' } } ], namespace: 'example-namespace', usage: {readUnits: 1} } ``` ```java Java theme={null} class QueryResponseWithUnsignedIndices { matches: [ScoredVectorWithUnsignedIndices { score: 10.34375 id: vec2 values: [] metadata: fields { key: "category" value { string_value: "technology" } } fields { key: "chunk_text" value { string_value: "Analysts suggest that AAPL\'\\\'\'s upcoming Q4 product launch event might solidify its position in the premium smartphone market." } } fields { key: "quarter" value { string_value: "Q4" } } sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices { indicesWithUnsigned32Int: [] values: [] } }, ScoredVectorWithUnsignedIndices { score: 5.8638916 id: vec3 values: [] metadata: fields { key: "category" value { string_value: "technology" } } fields { key: "chunk_text" value { string_value: "AAPL\'\\\'\'s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production" } } fields { key: "quarter" value { string_value: "Q3" } } sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices { indicesWithUnsigned32Int: [] values: [] } }, ScoredVectorWithUnsignedIndices { score: 5.3671875 id: vec1 values: [] metadata: fields { key: "category" value { string_value: "technology" } } fields { key: "chunk_text" value { string_value: "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones." } } fields { key: "quarter" value { string_value: "Q3" } } sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices { indicesWithUnsigned32Int: [] values: [] } }] namespace: example-namespace usage: read_units: 1 } ``` ```go Go theme={null} { "matches": [ { "vector": { "id": "vec2", "metadata": { "category": "technology", "quarter": "Q4", "chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market." } }, "score": 10.904296 }, { "vector": { "id": "vec3", "metadata": { "category": "technology", "quarter": "Q3", "chunk_text": "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production" } }, "score": 6.4801025 }, { "vector": { "id": "vec1", "metadata": { "category": "technology", "quarter": "Q3", "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones" } }, "score": 5.3671875 } ], "usage": { "read_units": 1 }, "namespace": "example-namespace" } ``` ```json curl theme={null} { "results": [], "matches": [ { "id": "vec2", "score": 10.9042969, "values": [], "metadata": { "chunk_text": "Analysts suggest that AAPL'''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4" } }, { "id": "vec3", "score": 6.48010254, "values": [], "metadata": { "chunk_text": "AAPL'''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.", "category": "technology", "quarter": "Q3" } }, { "id": "vec1", "score": 5.3671875, "values": [], "metadata": { "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "category": "technology", "quarter": "Q3" } } ], "namespace": "example-namespace", "usage": { "readUnits": 1 } } ``` ## Search with a record ID When you search with a record ID, Pinecone uses the sparse vector associated with the record as the query. To search an index of sparse vectors with a record ID, use the [`query`](/reference/api/latest/data-plane/query) operation with the following parameters: * `namespace`: The [namespace](/guides/index-data/indexing-overview#namespaces) to query. To use the default namespace, set to `"__default__"`. * `id`: The unique record ID containing the sparse vector to use as the query. * `top_k`: The number of results to return. * `include_values`: Whether to include the vector values of the matching records in the response. Defaults to `false`. * `include_metadata`: Whether to include the metadata of the matching records in the response. Defaults to `false`. When querying with `top_k` over 1000, for optimal performance set `include_values=false` and `include_metadata=false` to return only IDs and scores. Since vectors values are retrieved from object storage, include them in your query results only when you need them (especially with higher `top_k` values). For details, see [Decrease latency](/guides/optimize/decrease-latency#avoid-including-vector-values-when-not-needed). For example, the following code uses an ID to search for the 3 records in the `example-namespace` namespace that best match the sparse vector in the record: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.query( namespace="example-namespace", id="rec2", top_k=3, include_metadata=True, include_values=False ) ``` ```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/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const queryResponse = await index.namespace('example-namespace').query({ id: 'rec2', topK: 3, includeValues: false, includeMetadata: true, }); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices; public class QueryExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); QueryResponseWithUnsignedIndices queryRespone = index.queryByVectorId(3, "rec2", "example-namespace", null, false, true); System.out.println(queryResponse); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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/manage-data/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) } vectorId := "rec2" res, err := idxConnection.QueryByVectorId(ctx, &pinecone.QueryByVectorIdRequest{ VectorId: vectorId, TopK: 3, IncludeValues: false, IncludeMetadata: true, }) if err != nil { log.Fatalf("Error encountered when querying by vector ID `%v`: %v", vectorId, err) } else { fmt.Printf(prettifyStruct(res.Matches)) } } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/query" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "id": "rec2", "namespace": "example-namespace", "topK": 3, "includeMetadata": true, "includeValues": false }' ``` ## Filter by required terms This feature is in [public preview](/release-notes/feature-availability) and is available only on the `2025-10` version of the API. See [limitations](#limitations) for details. When [searching with text](#search-with-text), you can specify a list of terms that must be present in each lexical search result. This is especially useful for: * **Precision filtering**: Ensuring specific entities or concepts appear in results * **Quality control**: Filtering out results that don't contain essential keywords * **Domain-specific searches**: Requiring domain-specific terminology in results * **Entity-based filtering**: Ensuring specific people, places, or things are mentioned To filter by required terms, add `match_terms` to your query, specifying the `terms` to require and the `strategy` to use. Currently, `all` is the only strategy supported (all terms must be present). For example, the following request searches for records about Tesla's stock performance while ensuring both "Tesla" and "stock" appear in each result: ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/records/namespaces/example-namespace/search" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: unstable" \ -d '{ "query": { "inputs": { "text": "What is the current outlook for Tesla stock performance?" }, "top_k": 3, "match_terms": { "terms": ["Tesla", "stock"], "strategy": "all" } }, "fields": ["chunk_text"] }' ``` The response includes only records that contain both "Tesla" and "stock": ```json theme={null} { "result": { "hits": [ { "_id": "tesla_q4_earnings", "_score": 9.82421875, "fields": { "chunk_text": "Tesla stock surged 8% in after-hours trading following strong Q4 earnings that exceeded analyst expectations. The company reported record vehicle deliveries and improved profit margins." } }, { "_id": "tesla_competition_analysis", "_score": 7.49066162109375, "fields": { "chunk_text": "Tesla stock faces increasing competition from traditional automakers entering the electric vehicle market. However, analysts maintain that Tesla's technological lead and brand recognition provide significant advantages." } }, { "_id": "tesla_production_update", "_score": 6.3671875, "fields": { "chunk_text": "Tesla stock performance is closely tied to production capacity at its Gigafactories. Recent expansion announcements suggest the company is positioning for continued growth in global markets." } } ] }, "usage": { "embed_total_tokens": 18, "read_units": 1 } } ``` Without the `match_terms` filter, you might get results like: * "Tesla cars are popular in California" (mentions Tesla but not stock) * "Stock market volatility affects tech companies" (mentions stock but not Tesla) * "Electric vehicle sales are growing" (neither Tesla nor stock) ### Limitations * **Integrated indexes only**: Filtering by required terms is supported only for [indexes with integrated embedding](/guides/index-data/indexing-overview#integrated-embedding). * **Post-processing filter**: The filtering happens after the initial query, so potential matches that weren't included in the initial `top_k` results won't appear in the final results * **No phrase matching**: Terms are matched individually in any order and location. * **No case-sensitivity**: Terms are normalized during processing. # Reciprocal rank fusion Source: https://docs.pinecone.io/guides/search/reciprocal-rank-fusion Combine results from separate Pinecone searches into a single ranking with reciprocal rank fusion (RRF), a client-side method that fuses rankings, not scores. The examples below use the [document API](/guides/search/full-text-search), which is in [public preview](/guides/search/full-text-search#public-preview). Reciprocal rank fusion itself is a client-side method and works with the results of any Pinecone search. When you rank the same set of documents two different ways, for example, a [full-text (BM25) search](/guides/search/full-text-search) and a [semantic (dense-vector) search](/guides/search/semantic-search), the scores live on different, incomparable scales. Adding or averaging the raw scores is not meaningful, and one signal usually dominates. **Reciprocal rank fusion (RRF)** combines them by fusing the *rankings* instead of the scores, so no normalization or per-signal weighting is required. Today, you run each search separately, then apply RRF to their results in your client (server-side fusion is coming). ## When to use it Reach for RRF whenever you combine results from separate searches and want each to contribute to the final ranking, most commonly full-text (BM25) with semantic (dense-vector). It's a robust default that works without normalizing scores or tuning per-signal weights. ## How it works RRF scores each document by summing `1 / (k + rank)` across every ranking it appears in, where `rank` is the document's 1-based position in that ranking and `k` is a constant (the [original RRF paper](https://dl.acm.org/doi/10.1145/1571941.1572114) uses `k=60`). A document ranked highly in multiple searches accumulates the highest fused score. A document absent from a ranking gets nothing from it. Because only rank position matters, scores never need to be normalized. ```python Python theme={null} def reciprocal_rank_fusion(rankings, k=60): """Fuse ranked lists of document IDs into one RRF-scored ranking. Each ranking is a list of `_id`s in rank order (best first). Returns a dict mapping `_id` to its fused score. """ scores = {} for ranking in rankings: for rank, doc_id in enumerate(ranking, start=1): scores[doc_id] = scores.get(doc_id, 0.0) + 1.0 / (k + rank) return scores ``` ## Combine two searches This assumes an index whose [schema](/guides/search/full-text-search#schema-definition) declares an FTS-enabled `string` field (`body`) and a `dense_vector` field (`embedding`). Run each search independently, pass the ranked `_id`s to `reciprocal_rank_fusion`, then sort by the fused score. Here, a full-text search and a semantic search over the same index are fused into one top-10 ranking: ```python Python theme={null} import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) index = pc.preview.index(name="docs-example") query = "how do I reset my password?" fetch_k = 50 # fetch deeper than the final top_k so weaker-but-present signals still count # 1. Full-text (BM25) search. text_hits = index.documents.search( namespace="__default__", top_k=fetch_k, score_by=[{"type": "text", "field": "body", "query": query}], include_fields=["*"], ).matches # 2. Semantic (dense-vector) search. Embed the query with the same model as your documents. query_embedding = pc.inference.embed( model="llama-text-embed-v2", inputs=[query], parameters={"input_type": "query"}, ) dense_hits = index.documents.search( namespace="__default__", top_k=fetch_k, score_by=[{"type": "dense_vector", "field": "embedding", "values": query_embedding[0]["values"]}], include_fields=["*"], ).matches # 3. Fuse the two rankings client-side (reciprocal_rank_fusion is defined in "How it works" above). fused = reciprocal_rank_fusion([ [m._id for m in text_hits], [m._id for m in dense_hits], ]) # 4. Sort by fused score and keep the top results. by_id = {m._id: m for m in text_hits} for m in dense_hits: by_id.setdefault(m._id, m) top_k = 10 for doc_id in sorted(fused, key=fused.get, reverse=True)[:top_k]: print(doc_id, fused[doc_id], getattr(by_id[doc_id], "body", "")) ``` ## Tuning and extensions * **`fetch_k`** (a variable in this example, not an API parameter) controls how deep each ranking is fetched before fusing. Raise it so a document that ranks well in one search but outside the top of the other still contributes. It should be at least your final `top_k`. * **`k`** (default 60) controls how much a single ranking's top positions dominate the fused order. A larger `k` flattens the influence of any single top-ranked result. * **Latency.** Run the searches in parallel (for example with `asyncio` or threads) so you pay the slowest search's latency, not the sum. * **Weighting.** To favor one signal over another, weight each ranking's contribution (multiply its `1 / (k + rank)` terms by a per-ranking weight). It's a powerful relevance-tuning lever and can warrant its own guide; this page uses the unweighted default. ### Merge more than two rankings RRF extends to any number of rankings. Pass more lists to `reciprocal_rank_fusion`; each additional search contributes another ranked list of `_id`s: ```python Python theme={null} fused = reciprocal_rank_fusion([ [m._id for m in text_hits], [m._id for m in dense_hits], [m._id for m in sparse_hits], # e.g., a sparse-vector search ]) ``` # Rerank results Source: https://docs.pinecone.io/guides/search/rerank-results Improve retrieval quality by reranking initial search results with a hosted or external model to surface the most relevant matches for RAG. Reranking is used as part of a two-stage vector retrieval process to improve the quality of results. You first query an index for a given number of relevant results, and then you send the query and results to a reranking model. The reranking model scores the results based on their semantic relevance to the query and returns a new, more accurate ranking. This approach is one of the simplest methods for improving quality in retrieval augmented generation (RAG) pipelines. Pinecone provides [hosted reranking models](#reranking-models) so it's easy to manage two-stage vector retrieval on a single platform. You can use a hosted model to rerank results as an integrated part of a query, or you can use a hosted model or external model to rerank results as a standalone operation. To run through this guide in your browser, see the [Rerank example notebook](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/pinecone-reranker.ipynb). ## Integrated reranking To rerank initial results as an integrated part of a query, without any extra steps, use the [`search`](/reference/api/latest/data-plane/search_records) operation with the `rerank` parameter, including the [hosted reranking model](#reranking-models) you want to use, the number of reranked results to return, and the fields to use for reranking, if different than the main query. For example, the following code searches for the 3 records most semantically related to a query text and uses the `hosted bge-reranker-v2-m3` model to rerank the results and return only the 2 most relevant documents: ```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/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") ranked_results = index.search( namespace="example-namespace", query={ "inputs": {"text": "Disease prevention"}, "top_k": 4 }, rerank={ "model": "bge-reranker-v2-m3", "top_n": 2, "rank_fields": ["chunk_text"] }, fields=["category", "chunk_text"] ) print(ranked_results) ``` ```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/manage-data/target-an-index const namespace = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace"); const response = await namespace.searchRecords({ query: { topK: 2, inputs: { text: 'Disease prevention' }, }, fields: ['chunk_text', 'category'], rerank: { model: 'bge-reranker-v2-m3', rankFields: ['chunk_text'], topN: 2, }, }); console.log(response); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import org.openapitools.db_data.client.ApiException; import org.openapitools.db_data.client.model.SearchRecordsRequestRerank; import org.openapitools.db_data.client.model.SearchRecordsResponse; import java.util.*; public class SearchText { public static void main(String[] args) throws ApiException { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "integrated-dense-java"); String query = "Disease prevention"; List fields = new ArrayList<>(); fields.add("category"); fields.add("chunk_text"); ListrankFields = new ArrayList<>(); rankFields.add("chunk_text"); SearchRecordsRequestRerank rerank = new SearchRecordsRequestRerank() .query(query) .model("bge-reranker-v2-m3") .topN(2) .rankFields(rankFields); SearchRecordsResponse recordsResponseReranked = index.searchRecordsByText(query, "example-namespace", fields,4, null, rerank); System.out.println(recordsResponseReranked); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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/manage-data/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) } topN := int32(2) res, err := idxConnection.SearchRecords(ctx, &pinecone.SearchRecordsRequest{ Query: pinecone.SearchRecordsQuery{ TopK: 3, Inputs: &map[string]interface{}{ "text": "Disease prevention", }, }, Rerank: &pinecone.SearchRecordsRerank{ Model: "bge-reranker-v2-m3", TopN: &topN, RankFields: []string{"chunk_text"}, }, Fields: &[]string{"chunk_text", "category"}, }) if err != nil { log.Fatalf("Failed to search records: %v", err) } fmt.Printf(prettifyStruct(res)) } ``` ```shell curl theme={null} INDEX_HOST="INDEX_HOST" NAMESPACE="YOUR_NAMESPACE" PINECONE_API_KEY="YOUR_API_KEY" curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: unstable" \ -d '{ "query": { "inputs": {"text": "Disease prevention"}, "top_k": 4 }, "rerank": { "model": "bge-reranker-v2-m3", "top_n": 2, "rank_fields": ["chunk_text"] }, "fields": ["category", "chunk_text"] }' ``` The response looks as follows. For each hit, the `_score` represents the relevance of a document to the query, normalized between 0 and 1, with scores closer to 1 indicating higher relevance. ```python Python theme={null} {'result': {'hits': [{'_id': 'rec3', '_score': 0.004399413242936134, 'fields': {'category': 'immune system', 'chunk_text': 'Rich in vitamin C and other ' 'antioxidants, apples ' 'contribute to immune health ' 'and may reduce the risk of ' 'chronic diseases.'}}, {'_id': 'rec4', '_score': 0.0029235430993139744, 'fields': {'category': 'endocrine system', 'chunk_text': 'The high fiber content in ' 'apples can also help regulate ' 'blood sugar levels, making ' 'them a favorable snack for ' 'people with diabetes.'}}]}, 'usage': {'embed_total_tokens': 8, 'read_units': 6, 'rerank_units': 1}} ``` ```javascript JavaScript theme={null} { result: { hits: [ { _id: 'rec3', _score: 0.004399413242936134, fields: { category: 'immune system', chunk_text: 'Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.' } }, { _id: 'rec4', _score: 0.0029235430993139744, fields: { category: 'endocrine system', chunk_text: 'The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.' } } ] }, usage: { readUnits: 6, embedTotalTokens: 8, rerankUnits: 1 } } ``` ```java Java theme={null} class SearchRecordsResponse { result: class SearchRecordsResponseResult { hits: [class Hit { id: rec3 score: 0.004399413242936134 fields: {category=immune system, chunk_text=Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.} additionalProperties: null }, class Hit { id: rec4 score: 0.0029235430993139744 fields: {category=endocrine system, chunk_text=The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.} additionalProperties: null }] additionalProperties: null } usage: class SearchUsage { readUnits: 6 embedTotalTokens: 13 rerankUnits: 1 additionalProperties: null } additionalProperties: null } ``` ```go Go theme={null} { "result": { "hits": [ { "_id": "rec3", "_score": 0.13683891, "fields": { "category": "immune system", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases." } }, { "_id": "rec4", "_score": 0.0029235430993139744, "fields": { "category": "endocrine system", "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes." } } ] }, "usage": { "read_units": 6, "embed_total_tokens": 8, "rerank_units": 1 } } ``` ```json curl theme={null} { "result": { "hits": [ { "_id": "rec3", "_score": 0.004433765076100826, "fields": { "category": "immune system", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases." } }, { "_id": "rec4", "_score": 0.0029121784027665854, "fields": { "category": "endocrine system", "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes." } } ] }, "usage": { "embed_total_tokens": 8, "read_units": 6, "rerank_units": 1 } } ``` ## Standalone reranking To rerank initial results as a standalone operation, use the [`rerank`](/reference/api/latest/inference/rerank) operation with the [hosted reranking model](#reranking-models) you want to use, the query results and the query, the number of ranked results to return, the field to use for reranking, and any other model-specific parameters. For example, the following code uses the hosted `bge-reranker-v2-m3` model to rerank the values of the `documents.chunk_text` fields based on their relevance to the query and return only the 2 most relevant documents, along with their score: ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ranked_results = pc.inference.rerank( model="bge-reranker-v2-m3", query="What is AAPL's outlook, considering both product launches and market conditions?", documents=[ {"id": "vec2", "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market."}, {"id": "vec3", "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production."}, {"id": "vec1", "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones."}, ], top_n=2, rank_fields=["chunk_text"], return_documents=True, parameters={ "truncate": "END" } ) print(ranked_results) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); const rerankingModel = 'bge-reranker-v2-m3'; const query = "What is AAPL's outlook, considering both product launches and market conditions?"; const documents = [ { id: 'vec2', chunk_text: "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market." }, { id: 'vec3', chunk_text: "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production." }, { id: 'vec1', chunk_text: "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones." }, ]; const rerankOptions = { topN: 2, rankFields: ['chunk_text'], returnDocuments: true, parameters: { truncate: 'END' }, }; const rankedResults = await pc.inference.rerank( rerankingModel, query, documents, rerankOptions ); console.log(rankedResults); ``` ```java Java theme={null} import io.pinecone.clients.Inference; import io.pinecone.clients.Pinecone; import org.openapitools.inference.client.model.RerankResult; import org.openapitools.inference.client.ApiException; import java.util.*; public class RerankExample { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); Inference inference = pc.getInferenceClient(); // The model to use for reranking String model = "bge-reranker-v2-m3"; // The query to rerank documents against String query = "What is AAPL's outlook, considering both product launches and market conditions?"; // Add the documents to rerank List> documents = new ArrayList<>(); Map doc1 = new HashMap<>(); doc1.put("id", "vec2"); doc1.put("chunk_text", "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market."); documents.add(doc1); Map doc2 = new HashMap<>(); doc2.put("id", "vec3"); doc2.put("chunk_text", "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production"); documents.add(doc2); Map doc3 = new HashMap<>(); doc3.put("id", "vec1"); doc3.put("chunk_text", "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones."); documents.add(doc3); // The fields to rank the documents by. If not provided, the default is "text" List rankFields = Arrays.asList("chunk_text"); // The number of results to return sorted by relevance. Defaults to the number of inputs int topN = 2; // Whether to return the documents in the response boolean returnDocuments = true; // Additional model-specific parameters for the reranker Map parameters = new HashMap<>(); parameters.put("truncate", "END"); // Send ranking request RerankResult result = inference.rerank(model, query, documents, rankFields, topN, returnDocuments, parameters); // Get ranked data System.out.println(result.getData()); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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) } rerankModel := "bge-reranker-v2-m3" topN := 2 returnDocuments := true documents := []pinecone.Document{ {"id": "vec2", "chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market."}, {"id": "vec3", "chunk_text": "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production."}, {"id": "vec1", "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones."}, } ranking, err := pc.Inference.Rerank(ctx, &pinecone.RerankRequest{ Model: rerankModel, Query: "What is AAPL's outlook, considering both product launches and market conditions?", ReturnDocuments: &returnDocuments, TopN: &topN, RankFields: &[]string{"chunk_text"}, Documents: documents, }) if err != nil { log.Fatalf("Failed to rerank: %v", err) } fmt.Printf(prettifyStruct(ranking)) } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl https://api.pinecone.io/rerank \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Api-Key: $PINECONE_API_KEY" \ -d '{ "model": "bge-reranker-v2-m3", "query": "What is AAPL'\''s outlook, considering both product launches and market conditions?", "documents": [ {"id": "vec2", "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market."}, {"id": "vec3", "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production."}, {"id": "vec1", "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones."} ], "top_n": 2, "rank_fields": ["chunk_text"], "return_documents": true, "parameters": { "truncate": "END" } }' ``` The response looks as follows. For each hit, the \_score represents the relevance of a document to the query, normalized between 0 and 1, with scores closer to 1 indicating higher relevance. ```python Python theme={null} RerankResult( model='bge-reranker-v2-m3', data=[{ index=0, score=0.004166256, document={ id='vec2', chunk_text="Analysts suggest that AAPL'''s upcoming Q4 product launch event might solidify its position in the premium smartphone market." } },{ index=2, score=0.0011513996, document={ id='vec1', chunk_text='AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.' } }], usage={'rerank_units': 1} ) ``` ```javascript JavaScript theme={null} { model: 'bge-reranker-v2-m3', data: [ { index: 0, score: 0.004166256, document: [id: 'vec2', chunk_text: "Analysts suggest that AAPL'''s upcoming Q4 product launch event might solidify its position in the premium smartphone market."] }, { index: 2, score: 0.0011513996, document: [id: 'vec1', chunk_text: 'AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.'] } ], usage: { rerankUnits: 1 } } ``` ```java Java theme={null} [class RankedDocument { index: 0 score: 0.0063143647 document: {id=vec2, chunk_text=Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.} additionalProperties: null }, class RankedDocument { index: 2 score: 0.0011513996 document: {id=vec1, chunk_text=AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.} additionalProperties: null }] ``` ```go Go theme={null} { "data": [ { "document": { "id": "vec2", "chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market." }, "index": 0, "score": 0.0063143647 }, { "document": { "id": "vec1", "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones." }, "index": 2, "score": 0.0011513996 } ], "model": "bge-reranker-v2-m3", "usage": { "rerank_units": 1 } } ``` ```json curl theme={null} { "model": "bge-reranker-v2-m3", "data": [ { "index": 0, "document": { "chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "id": "vec2" }, "score": 0.007606672 }, { "index": 3, "document": { "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "id": "vec1" }, "score": 0.0013406205 } ], "usage": { "rerank_units": 1 } } ``` ## Rerank results on the default field To [rerank search results](/reference/api/latest/inference/rerank), specify a [supported reranking model](/guides/search/rerank-results#reranking-models), and provide documents and a query as well as other model-specific parameters. By default, Pinecone expects the documents to be in the `documents.text` field. For example, the following request uses the `bge-reranker-v2-m3` reranking model to rerank the values of the `documents.text` field based on their relevance to the query, `"The tech company Apple is known for its innovative products like the iPhone."`. With `truncate` set to `"END"`, the input sequence (`query` + `document`) is truncated at the token limit (`1024`); to return an error instead, you'd set `truncate` to `"NONE"` or leave the parameter out. ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") result = pc.inference.rerank( model="bge-reranker-v2-m3", query="The tech company Apple is known for its innovative products like the iPhone.", documents=[ {"id": "vec1", "text": "Apple is a popular fruit known for its sweetness and crisp texture."}, {"id": "vec2", "text": "Many people enjoy eating apples as a healthy snack."}, {"id": "vec3", "text": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."}, {"id": "vec4", "text": "An apple a day keeps the doctor away, as the saying goes."}, ], top_n=4, return_documents=True, parameters={ "truncate": "END" } ) print(result) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); const rerankingModel = 'bge-reranker-v2-m3'; const query = 'The tech company Apple is known for its innovative products like the iPhone.'; const documents = [ { id: 'vec1', text: 'Apple is a popular fruit known for its sweetness and crisp texture.' }, { id: 'vec2', text: 'Many people enjoy eating apples as a healthy snack.' }, { id: 'vec3', text: 'Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces.' }, { id: 'vec4', text: 'An apple a day keeps the doctor away, as the saying goes.' }, ]; const rerankOptions = { topN: 4, returnDocuments: true, parameters: { truncate: 'END' }, }; const response = await pc.inference.rerank( rerankingModel, query, documents, rerankOptions ); console.log(response); ``` ```java Java theme={null} import io.pinecone.clients.Inference; import io.pinecone.clients.Pinecone; import org.openapitools.inference.client.model.RerankResult; import org.openapitools.inference.client.ApiException; import java.util.*; public class RerankExample { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); Inference inference = pc.getInferenceClient(); // The model to use for reranking String model = "bge-reranker-v2-m3"; // The query to rerank documents against String query = "The tech company Apple is known for its innovative products like the iPhone."; // Add the documents to rerank List> documents = new ArrayList<>(); Map doc1 = new HashMap<>(); doc1.put("id", "vec1"); doc1.put("text", "Apple is a popular fruit known for its sweetness and crisp texture."); documents.add(doc1); Map doc2 = new HashMap<>(); doc2.put("id", "vec2"); doc2.put("text", "Many people enjoy eating apples as a healthy snack."); documents.add(doc2); Map doc3 = new HashMap<>(); doc3.put("id", "vec3"); doc3.put("text", "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."); documents.add(doc3); Map doc4 = new HashMap<>(); doc4.put("id", "vec4"); doc4.put("text", "An apple a day keeps the doctor away, as the saying goes."); documents.add(doc4); // The fields to rank the documents by. If not provided, the default is "text" List rankFields = Arrays.asList("text"); // The number of results to return sorted by relevance. Defaults to the number of inputs int topN = 4; // Whether to return the documents in the response boolean returnDocuments = true; // Additional model-specific parameters for the reranker Map parameters = new HashMap<>(); parameters.put("truncate", "END"); // Send ranking request RerankResult result = inference.rerank(model, query, documents, rankFields, topN, returnDocuments, parameters); // Get ranked data System.out.println(result.getData()); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } rerankModel := "bge-reranker-v2-m3" topN := 4 returnDocuments := true documents := []pinecone.Document{ {"id": "vec1", "text": "Apple is a popular fruit known for its sweetness and crisp texture."}, {"id": "vec2", "text": "Many people enjoy eating apples as a healthy snack."}, {"id": "vec3", "text": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."}, {"id": "vec4", "text": "An apple a day keeps the doctor away, as the saying goes."}, } ranking, err := pc.Inference.Rerank(ctx, &pinecone.RerankRequest{ Model: rerankModel, Query: "The tech company Apple is known for its innovative products like the iPhone.", ReturnDocuments: &returnDocuments, TopN: &topN, RankFields: &[]string{"text"}, Documents: documents, }) if err != nil { log.Fatalf("Failed to rerank: %v", err) } fmt.Printf("Rerank result: %+v\n", ranking) } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl https://api.pinecone.io/rerank \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Api-Key: $PINECONE_API_KEY" \ -d '{ "model": "bge-reranker-v2-m3", "query": "The tech company Apple is known for its innovative products like the iPhone.", "return_documents": true, "top_n": 4, "documents": [ {"id": "vec1", "text": "Apple is a popular fruit known for its sweetness and crisp texture."}, {"id": "vec2", "text": "Many people enjoy eating apples as a healthy snack."}, {"id": "vec3", "text": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."}, {"id": "vec4", "text": "An apple a day keeps the doctor away, as the saying goes."} ], "parameters": { "truncate": "END" } }' ``` The returned object contains documents with relevance scores: Normalized between 0 and 1, the `score` represents the relevance of a passage to the query, with scores closer to 1 indicating higher relevance. ```python Python theme={null} RerankResult( model='bge-reranker-v2-m3', data=[ { index=2, score=0.48357219, document={id="vec3", text="Apple Inc. has re..."} }, { index=0, score=0.048405956, document={id="vec1", text="Apple is a popula..."} }, { index=3, score=0.007846239, document={id="vec4", text="An apple a day ke..."} }, { index=1, score=0.0006563728, document={id="vec2", text="Many people enjoy..."} } ], usage={'rerank_units': 1} ) ``` ```javascript JavaScript theme={null} { model: 'bge-reranker-v2-m3', data: [ { index: 2, score: 0.48357219, document: [Object] }, { index: 0, score: 0.048405956, document: [Object] }, { index: 3, score: 0.007846239, document: [Object] }, { index: 1, score: 0.0006563728, document: [Object] } ], usage: { rerankUnits: 1 } } ``` ```java Java theme={null} [class RankedDocument { index: 2 score: 0.48357219 document: {id=vec3, text=Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces.} additionalProperties: null }, class RankedDocument { index: 0 score: 0.048405956 document: {id=vec1, text=Apple is a popular fruit known for its sweetness and crisp texture.} additionalProperties: null }, class RankedDocument { index: 3 score: 0.007846239 document: {id=vec4, text=An apple a day keeps the doctor away, as the saying goes.} additionalProperties: null }, class RankedDocument { index: 1 score: 0.0006563728 document: {id=vec2, text=Many people enjoy eating apples as a healthy snack.} additionalProperties: null }] ``` ```go Go theme={null} Rerank result: { "data": [ { "document": { "id": "vec3", "text": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces." }, "index": 2, "score": 0.48357219 }, { "document": { "id": "vec1", "text": "Apple is a popular fruit known for its sweetness and crisp texture." }, "index": 0, "score": 0.048405956 }, { "document": { "id": "vec4", "text": "An apple a day keeps the doctor away, as the saying goes." }, "index": 3, "score": 0.007846239 }, { "document": { "id": "vec2", "text": "Many people enjoy eating apples as a healthy snack." }, "index": 1, "score": 0.0006563728 } ], "model": "bge-reranker-v2-m3", "usage": { "rerank_units": 1 } } ``` ```JSON curl theme={null} { "data":[ { "index":2, "document":{ "id":"vec3", "text":"Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces." }, "score":0.47654688 }, { "index":0, "document":{ "id":"vec1", "text":"Apple is a popular fruit known for its sweetness and crisp texture." }, "score":0.047963805 }, { "index":3, "document":{ "id":"vec4", "text":"An apple a day keeps the doctor away, as the saying goes." }, "score":0.007587992 }, { "index":1, "document":{ "id":"vec2", "text":"Many people enjoy eating apples as a healthy snack." }, "score":0.0006491712 } ], "usage":{ "rerank_units":1 } } ``` ## Rerank results on a custom field To [rerank results](/reference/api/latest/inference/rerank) on a field other than `documents.text`, provide the `rank_fields` parameter to specify the fields on which to rerank. The [`bge-reranker-v2-m3`](#bge-reranker-v2-m3) and [`pinecone-rerank-v0`](#pinecone-rerank-v0) models support only a single rerank field. [`cohere-rerank-4-fast`](#cohere-rerank-4-fast) and [`cohere-rerank-3.5`](#cohere-rerank-3-5) support multiple rerank fields, ranked based on the order of the fields specified. For example, the following request reranks documents based on the values of the `documents.my_field` field: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") result = pc.inference.rerank( model="bge-reranker-v2-m3", query="The tech company Apple is known for its innovative products like the iPhone.", documents=[ {"id": "vec1", "my_field": "Apple is a popular fruit known for its sweetness and crisp texture."}, {"id": "vec2", "my_field": "Many people enjoy eating apples as a healthy snack."}, {"id": "vec3", "my_field": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."}, {"id": "vec4", "my_field": "An apple a day keeps the doctor away, as the saying goes."}, ], rank_fields=["my_field"], top_n=4, return_documents=True, parameters={ "truncate": "END" } ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); const rerankingModel = 'bge-reranker-v2-m3'; const query = 'The tech company Apple is known for its innovative products like the iPhone.'; const documents = [ { id: 'vec1', my_field: 'Apple is a popular fruit known for its sweetness and crisp texture.' }, { id: 'vec2', my_field: 'Many people enjoy eating apples as a healthy snack.' }, { id: 'vec3', my_field: 'Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces.' }, { id: 'vec4', my_field: 'An apple a day keeps the doctor away, as the saying goes.' }, ]; const rerankOptions = { rankFields: ['my_field'], topN: 4, returnDocuments: true, parameters: { truncate: "END" }, }; const response = await pc.inference.rerank( rerankingModel, query, documents, rerankOptions ); console.log(response); ``` ```java Java theme={null} import io.pinecone.clients.Inference; import io.pinecone.clients.Pinecone; import org.openapitools.inference.client.model.RerankResult; import org.openapitools.inference.client.ApiException; import java.util.*; public class RerankExample { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); Inference inference = pc.getInferenceClient(); // The model to use for reranking String model = "bge-reranker-v2-m3"; // The query to rerank documents against String query = "The tech company Apple is known for its innovative products like the iPhone."; // Add the documents to rerank List> documents = new ArrayList<>(); Map doc1 = new HashMap<>(); doc1.put("id", "vec1"); doc1.put("my_field", "Apple is a popular fruit known for its sweetness and crisp texture."); documents.add(doc1); Map doc2 = new HashMap<>(); doc2.put("id", "vec2"); doc2.put("my_field", "Many people enjoy eating apples as a healthy snack."); documents.add(doc2); Map doc3 = new HashMap<>(); doc3.put("id", "vec3"); doc3.put("my_field", "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."); documents.add(doc3); Map doc4 = new HashMap<>(); doc4.put("id", "vec4"); doc4.put("my_field", "An apple a day keeps the doctor away, as the saying goes."); documents.add(doc4); // The fields to rank the documents by. If not provided, the default is "text" List rankFields = Arrays.asList("my_field"); // The number of results to return sorted by relevance. Defaults to the number of inputs int topN = 2; // Whether to return the documents in the response boolean returnDocuments = true; // Additional model-specific parameters for the reranker Map parameters = new HashMap<>(); parameters.put("truncate", "END"); // Send ranking request RerankResult result = inference.rerank(model, query, documents, rankFields, topN, returnDocuments, parameters); // Get ranked data System.out.println(result.getData()); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) 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) } rerankModel := "bge-reranker-v2-m3" topN := 4 returnDocuments := true documents := []pinecone.Document{ {"id": "vec1", "my_field": "Apple is a popular fruit known for its sweetness and crisp texture."}, {"id": "vec2", "my_field": "Many people enjoy eating apples as a healthy snack."}, {"id": "vec3", "my_field": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."}, {"id": "vec4", "my_field": "An apple a day keeps the doctor away, as the saying goes."}, } ranking, err := pc.Inference.Rerank(ctx, &pinecone.RerankRequest{ Model: rerankModel, Query: "The tech company Apple is known for its innovative products like the iPhone.", ReturnDocuments: &returnDocuments, TopN: &topN, RankFields: &[]string{"my_field"}, Documents: documents, }) if err != nil { log.Fatalf("Failed to rerank: %v", err) } fmt.Printf("Rerank result: %+v\n", ranking) } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl "https://api.pinecone.io/rerank" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Api-Key: $PINECONE_API_KEY" \ -d '{ "model": "bge-reranker-v2-m3", "query": "The tech company Apple is known for its innovative products like the iPhone.", "return_documents": true, "top_n": 4, "rank_fields": ["my_field"], "documents": [ {"id": "vec1", "my_field": "Apple is a popular fruit known for its sweetness and crisp texture."}, {"id": "vec2", "my_field": "Many people enjoy eating apples as a healthy snack."}, {"id": "vec3", "my_field": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."}, {"id": "vec4", "my_field": "An apple a day keeps the doctor away, as the saying goes."} ], "parameters": { "truncate": "END" } }' ``` ## Reranking models Pinecone hosts several reranking models so it's easy to manage two-stage vector retrieval on a single platform. You can use a hosted model to rerank results as an integrated part of a query, or you can use a hosted model to rerank results as a standalone operation. The following reranking models are hosted by Pinecone. To understand how cost is calculated for reranking, see [Reranking cost](/guides/manage-cost/understanding-cost#reranking). To get model details via the API, see [List models](/reference/api/latest/inference/list_models) and [Describe a model](/reference/api/latest/inference/describe_model). [`cohere-rerank-4-fast`](/models/cohere-rerank-4-fast) is Cohere's latest reranking model (Cohere Rerank 4.0 Fast), improving relevance quality for a wide range of enterprise search applications. Cohere Rerank 4.0 is hosted on Azure AI under the Global Standard deployment type, and requests may be processed in regions outside the United States. **Details** * Modality: Text * Max tokens per document: 8,192 * Max documents: 250 The relevance scores produced by `cohere-rerank-4-fast` are not directly comparable to those from `cohere-rerank-3.5`. This does not affect sorting, but any application logic that uses a fixed score threshold to make decisions must be re-calibrated for the new model. For rate limits, see [Rerank requests per minute](/reference/api/database-limits#rerank-requests-per-minute-per-model) and [Rerank requests per month](/reference/api/database-limits#rerank-requests-per-month-per-model). **Parameters** The `cohere-rerank-4-fast` model supports the following parameters: | Parameter | Type | Required/Optional | Description | Default | | :------------------- | :--------------- | :---------------- | :--------------------------------------------------------------------------------- | :--------- | | `max_tokens_per_doc` | integer | Optional | Documents longer than this are truncated. Max `4096`. | `1024` | | `rank_fields` | array of strings | Optional | The fields to use for reranking, in priority order (e.g., `["field1", "field2"]`). | `["text"]` | `cohere-rerank-3.5` is deprecated as of July 1, 2026. Starting August 1, 2026, requests to `cohere-rerank-3.5` are automatically served by [`cohere-rerank-4-fast`](#cohere-rerank-4-fast). Migrate your rerank requests to `cohere-rerank-4-fast` before then to control the transition yourself. Because `cohere-rerank-4-fast` returns different relevance scores, re-tune any hard-coded score thresholds before the transition. [`cohere-rerank-3.5`](/models/cohere-rerank-3.5) is Cohere's previous-generation reranking model, balancing performance and latency for a wide range of enterprise search applications. **Details** * Modality: Text * Max tokens per query and document pair: 40,000 * Max documents: 200 For rate limits, see [Rerank requests per minute](/reference/api/database-limits#rerank-requests-per-minute-per-model) and [Rerank request per month](/reference/api/database-limits#rerank-requests-per-month-per-model). **Parameters** The `cohere-rerank-3.5` model supports the following parameters: | Parameter | Type | Required/Optional | Description | | | :------------------- | :--------------- | :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `max_chunks_per_doc` | integer | Optional | Long documents will be automatically truncated to the specified number of chunks. Accepted range: `1 - 3072`. | | | `rank_fields` | array of strings | Optional | The fields to use for reranking. The model reranks based on the order of the fields specified (e.g., `["field1", "field2", "field3"]`). | `["text"]` | [`bge-reranker-v2-m3`](/models/bge-reranker-v2-m3) is a high-performance, multilingual reranking model that works well on messy data and short queries expected to return medium-length passages of text (1-2 paragraphs). **Details** * Modality: Text * Max tokens per query and document pair: 1024 * Max documents: 100 For rate limits, see [Rerank requests per minute](/reference/api/database-limits#rerank-requests-per-minute-per-model) and [Rerank request per month](/reference/api/database-limits#rerank-requests-per-month-per-model). **Parameters** The `bge-reranker-v2-m3` model supports the following parameters: | Parameter | Type | Required/Optional | Description | Default | | :------------ | :--------------- | :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------- | | `truncate` | string | Optional | How to handle inputs longer than those supported by the model. Accepted values: `END` or `NONE`.

`END` truncates the input sequence at the input token limit. `NONE` returns an error when the input exceeds the input token limit. | `NONE` | | `rank_fields` | array of strings | Optional | The field to use for reranking. The model supports only a single rerank field. | `["text"]` | [`pinecone-rerank-v0`](/models/pinecone-rerank-v0) is a state of the art reranking model that out-performs competitors on widely accepted benchmarks. It can handle chunks up to 512 tokens (1-2 paragraphs). **Details** * Modality: Text * Max tokens per query and document pair: 512 * Max documents: 100 For rate limits, see [Rerank requests per minute](/reference/api/database-limits#rerank-requests-per-minute-per-model) and [Rerank request per month](/reference/api/database-limits#rerank-requests-per-month-per-model). **Parameters** The `pinecone-rerank-v0` model supports the following parameters: | Parameter | Type | Required/Optional | Description | Default | | :------------ | :--------------- | :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------- | | `truncate` | string | Optional | How to handle inputs longer than those supported by the model. Accepted values: `END` or `NONE`.

`END` truncates the input sequence at the input token limit. `NONE` returns an error when the input exceeds the input token limit. | `END` | | `rank_fields` | array of strings | Optional | The field to use for reranking. The model supports only a single rerank field. | `["text"]` | # Search overview Source: https://docs.pinecone.io/guides/search/search-overview Compare Pinecone search types and choose the right retrieval approach: full-text (BM25), semantic (dense vector), sparse lexical, and hybrid. Searches consume [read units (RUs)](/guides/manage-cost/understanding-cost#read-units). See [Understanding cost](/guides/manage-cost/understanding-cost#query) for how query cost is calculated. ## Search types * [Full-text search](/guides/search/full-text-search) * [Semantic search](/guides/search/semantic-search) (dense-vector) * [Sparse-vector search (also called sparse-vector lexical search)](/guides/search/lexical-search) * [Hybrid search](/guides/search/hybrid-search) ## Choosing a search approach Pinecone supports four retrieval approaches. They differ in the signal they rank on and the index shape they require. ### Quick decision tree Walk through these questions in order — pick the first match. 1. **Do your queries share specific tokens with the data?** (Product names, error messages, source code, named entities, technical jargon, identifiers.) → **[Full-text search](/guides/search/full-text-search)**. BM25 ranks results that share tokens with the query; Lucene syntax adds boolean and phrase operators. 2. **Are your queries natural language where meaning matters more than exact wording?** (Synonyms, paraphrases, conceptual similarity.) → **[Semantic search](/guides/search/semantic-search)** with a dense vector field. 3. **Do you produce a learned sparse-vector representation upstream of Pinecone?** (For example, using [`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0) or your own sparse encoder.) → **[Sparse-vector lexical search](/guides/search/lexical-search)**. 4. **Do you need both semantic and keyword signals on the same data?** * **On a JSON-document workload** → **[Full-text search](/guides/search/full-text-search)** with a multi-field schema. Declare a `dense_vector` field alongside one or more FTS-enabled `string` fields. A single search request ranks by one signal; combine them by adding a text-match filter to a `dense_vector` query, or by running two searches and merging results client-side. * **On a vector-only records workload** → **[Hybrid search](/guides/search/hybrid-search)**. Store a dense vector and a sparse vector on each record in a single index (vector API). ### Approach details A useful gradient: **dense** ranks on concept (semantic similarity), **full-text search** ranks on strict character-level token matching (BM25), and **sparse-vector lexical search** sits between them — token-aware, but with learned per-token weights and term expansion. * **[Full-text search](/guides/search/full-text-search)** — **recommended** for keyword and phrase search over text content. You upsert typed JSON documents and rank with `score_by`: BM25 token matching on an FTS-enabled `string` field, Lucene query syntax (`query_string`), `dense_vector` similarity, or `sparse_vector` similarity. A single index with a document schema can mix all four field types, so it's also the recommended single-index path when a workload needs more than one signal (BM25 + dense, BM25 + sparse, etc.). * **[Semantic search](/guides/search/semantic-search) (dense-vector)** — for queries where intent and meaning matter more than exact keyword matches (synonyms, paraphrases, conceptual similarity). Uses dense embeddings. * **[Sparse-vector search (also called sparse-vector lexical search)](/guides/search/lexical-search)** — recommended for workflows that use a learned sparse-vector model (for example, [`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0)) or where the application owns the sparse-vector representation directly. For general-purpose keyword and phrase retrieval over text, start with full-text search. * **[Hybrid search](/guides/search/hybrid-search)** — combines dense and sparse vectors in a single index (vector API) for vector-centric workflows that need both semantic and lexical signals. For document-centric workflows that combine keyword matching with vector ranking, the most common pattern is dense (or sparse) ranking restricted by a text-match filter on an FTS-enabled `string` field — for example, semantic search across a corpus narrowed to documents containing an exact phrase. To weight BM25 and dense rankings against each other, run separate searches and merge the results client-side. Once you've chosen an approach, see [Data modeling](/guides/index-data/data-modeling) to structure your documents or records, then [Create an index](/guides/index-data/create-an-index) to set it up. ## Optimization * [Filter by metadata](/guides/search/filter-by-metadata) * [Rerank results](/guides/search/rerank-results) * [Parallel queries](/guides/search/semantic-search#parallel-queries) ## Limits | Metric | Limit | | :---------------- | :----- | | Max `top_k` value | 10,000 | | Max result size | 4MB | The query result size is affected by the dimension of the dense vectors and whether or not dense vector values and metadata are included in the result. If a query fails due to exceeding the 4MB result size limit, choose a lower `top_k` value, or use `include_metadata=False` or `include_values=False` to exclude metadata or values from the result. For better performance, especially with higher `top_k` values, avoid including vector values unless you need them. ## Cost * To understand how cost is calculated for queries, see [Understanding cost](/guides/manage-cost/understanding-cost#query). * For up-to-date pricing information, see [Pricing](https://www.pinecone.io/pricing/). ## Data freshness Pinecone is eventually consistent, so there can be a slight delay before new or changed records are visible to queries. You can view index stats to [check data freshness](/guides/index-data/check-data-freshness). # Semantic search Source: https://docs.pinecone.io/guides/search/semantic-search Search a Pinecone index of dense vectors to find semantically similar records using text or vector queries, top_k results, and nearest neighbor lookup. This page shows you how to search an [index of dense vectors](/guides/index-data/indexing-overview#indexes-with-dense-vectors) for records that are most similar in meaning and context to a query. This is often called semantic search, nearest neighbor search, similarity search, or just vector search. Semantic search uses [dense vectors](https://www.pinecone.io/learn/vector-embeddings/). Each number in a dense vector corresponds to a point in a multidimensional space. Vectors that are closer together in that space are semantically similar. ## Search with text Searching with text is supported only for [indexes with integrated embedding](/guides/index-data/indexing-overview#integrated-embedding). To search an index of dense vectors with a query text, use the [`search_records`](/reference/api/latest/data-plane/search_records) operation with the following parameters: * The `namespace` to query. To use the default namespace, set the namespace to `"__default__"`. * The `query.inputs.text` parameter with the query text. Pinecone uses the embedding model integrated with the index to convert the text to a dense vector automatically. * The `query.top_k` parameter with the number of similar records to return. * Optionally, you can specify the `fields` to return in the response. If not specified, the response will include all fields. For example, the following code searches for the 2 records most semantically related to a query text: ```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/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") results = index.search( namespace="example-namespace", query={ "inputs": {"text": "Disease prevention"}, "top_k": 2 }, fields=["category", "chunk_text"] ) print(results) ``` ```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/manage-data/target-an-index const namespace = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace"); const response = await namespace.searchRecords({ query: { topK: 2, inputs: { text: 'Disease prevention' }, }, fields: ['chunk_text', 'category'], }); console.log(response); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import org.openapitools.db_data.client.ApiException; import org.openapitools.db_data.client.model.SearchRecordsResponse; import java.util.*; public class SearchText { public static void main(String[] args) throws ApiException { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "integrated-dense-java"); String query = "Disease prevention"; List fields = new ArrayList<>(); fields.add("category"); fields.add("chunk_text"); // Search the index SearchRecordsResponse recordsResponse = index.searchRecordsByText(query, "example-namespace", fields, 2, null, null); // Print the results System.out.println(recordsResponse); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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/manage-data/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) } res, err := idxConnection.SearchRecords(ctx, &pinecone.SearchRecordsRequest{ Query: pinecone.SearchRecordsQuery{ TopK: 2, Inputs: &map[string]interface{}{ "text": "Disease prevention", }, }, Fields: &[]string{"chunk_text", "category"}, }) if err != nil { log.Fatalf("Failed to search records: %v", err) } fmt.Printf(prettifyStruct(res)) } ``` ```shell curl theme={null} INDEX_HOST="INDEX_HOST" NAMESPACE="YOUR_NAMESPACE" PINECONE_API_KEY="YOUR_API_KEY" curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: unstable" \ -d '{ "query": { "inputs": {"text": "Disease prevention"}, "top_k": 2 }, "fields": ["category", "chunk_text"] }' ``` The response will look as follows. Each record is returned with a similarity score that represents its distance to the query vector, calculated according to the [similarity metric](/guides/index-data/create-an-index#similarity-metrics) for the index. ```python Python theme={null} {'result': {'hits': [{'_id': 'rec3', '_score': 0.8204272389411926, 'fields': {'category': 'immune system', 'chunk_text': 'Rich in vitamin C and other ' 'antioxidants, apples ' 'contribute to immune health ' 'and may reduce the risk of ' 'chronic diseases.'}}, {'_id': 'rec1', '_score': 0.7931625843048096, 'fields': {'category': 'digestive system', 'chunk_text': 'Apples are a great source of ' 'dietary fiber, which supports ' 'digestion and helps maintain a ' 'healthy gut.'}}]}, 'usage': {'embed_total_tokens': 8, 'read_units': 6}} ``` ```javascript JavaScript theme={null} { result: { hits: [ { _id: 'rec3', _score: 0.82042724, fields: { category: 'immune system', chunk_text: 'Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.' } }, { _id: 'rec1', _score: 0.7931626, fields: { category: 'digestive system', chunk_text: 'Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.' } } ] }, usage: { readUnits: 6, embedTotalTokens: 8 } } ``` ```java Java theme={null} class SearchRecordsResponse { result: class SearchRecordsResponseResult { hits: [class Hit { id: rec3 score: 0.8204272389411926 fields: {category=immune system, chunk_text=Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.} additionalProperties: null }, class Hit { id: rec1 score: 0.7931625843048096 fields: {category=endocrine system, chunk_text=Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.} additionalProperties: null }] additionalProperties: null } usage: class SearchUsage { readUnits: 6 embedTotalTokens: 13 } additionalProperties: null } ``` ```go Go theme={null} { "result": { "hits": [ { "_id": "rec3", "_score": 0.82042724, "fields": { "category": "immune system", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases." } }, { "_id": "rec1", "_score": 0.7931626, "fields": { "category": "digestive system", "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut." } } ] }, "usage": { "read_units": 6, "embed_total_tokens": 8 } } ``` ```json curl theme={null} { "result": { "hits": [ { "_id": "rec3", "_score": 0.82042724, "fields": { "category": "immune system", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases." } }, { "_id": "rec1", "_score": 0.7931626, "fields": { "category": "digestive system", "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut." } } ] }, "usage": { "embed_total_tokens": 8, "read_units": 6 } } ``` ## Search with a dense vector To search an index of dense vectors with a dense vector representation of a query, use the [`query`](/reference/api/latest/data-plane/query) operation with the following parameters: * The `namespace` to query. To use the default namespace, set the namespace to `"__default__"`. * The `vector` parameter with the dense vector values representing your query. * The `top_k` parameter with the number of results to return. * Optionally, you can set `include_values` and/or `include_metadata` to `true` to include the vector values and/or metadata of the matching records in the response. For better performance, especially with higher `top_k` values, avoid including vector values unless you need them. See [Decrease latency](/guides/optimize/decrease-latency#avoid-including-vector-values-when-not-needed) for more details. For example, the following code uses a dense vector representation of the query “Disease prevention” to search for the 3 most semantically similar records in the `example-namespaces` namespace: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.query( namespace="example-namespace", vector=[0.0236663818359375,-0.032989501953125, ..., -0.01041412353515625,0.0086669921875], top_k=3, include_metadata=True, include_values=False ) ``` ```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/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const queryResponse = await index.namespace('example-namespace').query({ vector: [0.0236663818359375,-0.032989501953125,...,-0.01041412353515625,0.0086669921875], topK: 3, includeValues: false, includeMetadata: true, }); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices; import java.util.Arrays; import java.util.List; public class QueryExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); List query = Arrays.asList(0.0236663818359375f, -0.032989501953125f, ..., -0.01041412353515625f, 0.0086669921875f); QueryResponseWithUnsignedIndices queryResponse = index.query(3, query, null, null, null, "example-namespace", null, false, true); System.out.println(queryResponse); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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/manage-data/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) } queryVector := []float32{0.0236663818359375,-0.032989501953125,...,-0.01041412353515625,0.0086669921875} res, err := idxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{ Vector: queryVector, TopK: 3, IncludeValues: false, includeMetadata: true, }) if err != nil { log.Fatalf("Error encountered when querying by vector: %v", err) } else { fmt.Printf(prettifyStruct(res)) } } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/query" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "vector": [0.0236663818359375,-0.032989501953125,...,-0.01041412353515625,0.0086669921875], "namespace": "example-namespace", "topK": 3, "includeMetadata": true, "includeValues": false }' ``` The response will look as follows. Each record is returned with a similarity score that represents its distance to the query vector, calculated according to the [similarity metric](/guides/index-data/create-an-index#similarity-metrics) for the index. ```python Python theme={null} {'matches': [{'id': 'rec3', 'metadata': {'category': 'immune system', 'chunk_text': 'Rich in vitamin C and other ' 'antioxidants, apples contribute to ' 'immune health and may reduce the ' 'risk of chronic diseases.'}, 'score': 0.82026422, 'values': []}, {'id': 'rec1', 'metadata': {'category': 'digestive system', 'chunk_text': 'Apples are a great source of ' 'dietary fiber, which supports ' 'digestion and helps maintain a ' 'healthy gut.'}, 'score': 0.793068111, 'values': []}, {'id': 'rec4', 'metadata': {'category': 'endocrine system', 'chunk_text': 'The high fiber content in apples ' 'can also help regulate blood sugar ' 'levels, making them a favorable ' 'snack for people with diabetes.'}, 'score': 0.780169606, 'values': []}], 'namespace': 'example-namespace', 'usage': {'read_units': 6}} ``` ```JavaScript JavaScript theme={null} { matches: [ { id: 'rec3', score: 0.819709897, values: [], sparseValues: undefined, metadata: [Object] }, { id: 'rec1', score: 0.792900264, values: [], sparseValues: undefined, metadata: [Object] }, { id: 'rec4', score: 0.780068815, values: [], sparseValues: undefined, metadata: [Object] } ], namespace: 'example-namespace', usage: { readUnits: 6 } } ``` ```java Java theme={null} class QueryResponseWithUnsignedIndices { matches: [ScoredVectorWithUnsignedIndices { score: 0.8197099 id: rec3 values: [] metadata: fields { key: "category" value { string_value: "immune system" } } fields { key: "chunk_text" value { string_value: "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases." } } sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices { indicesWithUnsigned32Int: [] values: [] } }, ScoredVectorWithUnsignedIndices { score: 0.79290026 id: rec1 values: [] metadata: fields { key: "category" value { string_value: "digestive system" } } fields { key: "chunk_text" value { string_value: "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut." } } sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices { indicesWithUnsigned32Int: [] values: [] } }, ScoredVectorWithUnsignedIndices { score: 0.7800688 id: rec4 values: [] metadata: fields { key: "category" value { string_value: "endocrine system" } } fields { key: "chunk_text" value { string_value: "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes." } } sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices { indicesWithUnsigned32Int: [] values: [] } }] namespace: example-namespace usage: read_units: 6 } ``` ```go Go theme={null} { "matches": [ { "vector": { "id": "rec3", "metadata": { "category": "immune system", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases." } }, "score": 0.8197099 }, { "vector": { "id": "rec1", "metadata": { "category": "digestive system", "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut." } }, "score": 0.79290026 }, { "vector": { "id": "rec4", "metadata": { "category": "endocrine system", "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes." } }, "score": 0.7800688 } ], "usage": { "read_units": 6 }, "namespace": "example-namespace" } ``` ```json curl theme={null} { "results": [], "matches": [ { "id": "rec3", "score": 0.820593238, "values": [], "metadata": { "category": "immune system", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases." } }, { "id": "rec1", "score": 0.792266726, "values": [], "metadata": { "category": "digestive system", "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut." } }, { "id": "rec4", "score": 0.780045748, "values": [], "metadata": { "category": "endocrine system", "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes." } } ], "namespace": "example-namespace", "usage": { "readUnits": 6 } } ``` ## Search with a record ID When you search with a record ID, Pinecone uses the dense vector associated with the record as the query. To search an index of dense vectors with a record ID, use the [`query`](/reference/api/latest/data-plane/query) operation with the following parameters: * The `namespace` to query. To use the default namespace, set the namespace to `"__default__"`. * The `id` parameter with the unique record ID containing the vector to use as the query. * The `top_k` parameter with the number of results to return. * Optionally, you can set `include_values` and/or `include_metadata` to `true` to include the vector values and/or metadata of the matching records in the response. For better performance, especially with higher `top_k` values, avoid including vector values unless you need them. See [Decrease latency](/guides/optimize/decrease-latency#avoid-including-vector-values-when-not-needed) for more details. For example, the following code uses an ID to search for the 3 records in the `example-namespace` namespace that are most semantically similar to the dense vector in the record: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.query( namespace="example-namespace", id="rec2", top_k=3, include_metadata=True, include_values=False ) ``` ```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/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const queryResponse = await index.namespace('example-namespace').query({ id: 'rec2', topK: 3, includeValues: false, includeMetadata: true, }); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices; public class QueryExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); QueryResponseWithUnsignedIndices queryRespone = index.queryByVectorId(3, "rec2", "example-namespace", null, false, true); System.out.println(queryResponse); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/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/manage-data/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) } vectorId := "rec2" res, err := idxConnection.QueryByVectorId(ctx, &pinecone.QueryByVectorIdRequest{ VectorId: vectorId, TopK: 3, IncludeValues: false, IncludeMetadata: true, }) if err != nil { log.Fatalf("Error encountered when querying by vector ID `%v`: %v", vectorId, err) } else { fmt.Printf(prettifyStruct(res.Matches)) } } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/query" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "id": "rec2", "namespace": "example-namespace", "topK": 3, "includeMetadata": true, "includeValues": false }' ``` ## Parallel queries Python SDK v6.0.0 and later provide `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). Async support makes it possible to use Pinecone with modern async web frameworks such as FastAPI, Quart, and Sanic, and can significantly increase the efficiency of running queries in parallel. For more details, see the [Async requests](/reference/sdks/python/overview#async-requests). Alternatively, you can run multi-threaded, synchronous queries in parallel. For example, the following code uses a thread pool to run multiple queries concurrently. This example assumes that you have a 1536-dimension serverless index called `docs-example` and the [Pinecone Python SDK](/reference/sdks/python/overview) and [`concurrent.futures`](https://docs.python.org/3/library/concurrent.futures.html#module-concurrent.futures) and [`numpy`](https://numpy.org/) packages installed. ```python theme={null} import os from pinecone import Pinecone from concurrent.futures import ThreadPoolExecutor # Get the API key from the environment variable and initialize Pinecone api_key = os.environ.get("PINECONE_API_KEY") pc = Pinecone(api_key=api_key) # Define the index name index_name = "docs-example" # Define the index index = pc.Index(index_name) # Define the function to run parallel queries def run_parallel_queries(vectors): """ Run a list of vectors in parallel using ThreadPoolExecutor. Parameters: vectors (list): A list of vectors. Returns: list: A list of query results. """ # Define the maximum number of concurrent queries MAX_CONCURRENT_QUERIES = 4 def run_query(vector): """ Run a single query. """ return index.query( namespace="example-namespace", vector=vector, top_k=3, include_values=True ) # Run the queries in parallel with ThreadPoolExecutor(max_workers=MAX_CONCURRENT_QUERIES) as executor: results = list(executor.map(run_query, vectors)) return results def test_parallel_queries(): """ Test the run_parallel_queries function with 20 random vectors. """ import numpy as np # Generate 20 random vectors of size 1536 and convert them to lists vectors = [np.random.rand(1536).tolist() for _ in range(20)] # Run the parallel queries results = run_parallel_queries(vectors) # Print the results for i, result in enumerate(results): print(f"Query {i+1} results: {result}") if __name__ == "__main__": test_parallel_queries() ``` # Authentication Source: https://docs.pinecone.io/reference/api/authentication Pinecone API authentication guide covering API key generation, SDK client setup, and HTTP header configuration for authorized requests. All requests to [Pinecone APIs](/reference/api/introduction) must contain a valid [API key](/guides/production/security-overview#api-keys) for the target project. ## Get an API key [Create a new API key](https://app.pinecone.io/organizations/-/projects/-/keys) in the Pinecone console, or use the connect widget below to generate a key.
Copy your generated key: ``` PINECONE_API_KEY="{{YOUR_API_KEY}}" # This API key has ReadWrite access to all indexes in your project. ``` ## Initialize a client When using a [Pinecone SDK](/reference/pinecone-sdks), initialize a client object with your API key and then reuse the authenicated client in subsquent function calls. For example: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key='YOUR_API_KEY') # Creates an index using the API key stored in the client 'pc'. pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud='aws', region='us-east-1' ) ) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); // Creates an index using the API key stored in the client 'pc'. await pc.createIndex({ name: 'docs-example', dimension: 1536, metric: 'cosine', spec: { serverless: { cloud: 'aws', region: 'us-east-1' } } }) ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.IndexModel; import org.openapitools.db_control.client.model.DeletionProtection; public class CreateServerlessIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); // Creates an index using the API key stored in the client 'pc'. pc.createServerlessIndex("docs-example", "cosine", 1536, "aws", "us-east-1"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v3/pinecone" ) 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) } indexName := "docs-example" vectorType := "dense" dimension := int32(1536) metric := pinecone.Cosine deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: indexName, VectorType: &vectorType, Dimension: &dimension, Metric: &metric, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: &deletionProtection, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", err) } else { fmt.Printf("Successfully created serverless index: %v", idx.Name) } } ``` ```shell curl theme={null} curl -s "https://api.pinecone.io/indexes" \ -H "Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud":"aws", "region": "us-east-1" } } }' ``` ## Add headers to an HTTP request All HTTP requests to Pinecone APIs must contain an `Api-Key` header that specifies a valid [API key](/guides/production/security-overview#api-keys) and must be encoded as JSON with the `Content-Type: application/json` header. For example: ```shell curl theme={null} curl https://api.pinecone.io/indexes \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud":"aws", "region": "us-east-1" } } }' ``` ## Troubleshooting Older versions of Pinecone required you to initialize a client with an `init` method that takes both `api_key` and `environment` parameters, for example: ```python Python theme={null} # Legacy initialization import pinecone pc = pinecone.init( api_key="PINECONE_API_KEY", environment="PINECONE_ENVIRONMENT" ) ``` ```javascript JavaScript theme={null} // Legacy initialization import { Pinecone } from '@pinecone-database/pinecone'; const pineconeClient = new PineconeClient(); await pineconeClient.init({ apiKey: 'PINECONE_API_KEY', environment: 'PINECONE_ENVIRONMENT', }); ``` In more recent versions of Pinecone, this has changed. Initialization no longer requires an `init` step, and cloud environment is defined for each index rather than an entire project. Client initialization now only requires an `api_key` parameter, for example: ```python Python theme={null} # New initialization from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` ```javascript JavaScript theme={null} // New initialization import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); ``` If you are receiving errors about initialization, upgrade your [Pinecone SDK](/reference/pinecone-sdks) to the latest version, for example: ```shell Python theme={null} # Upgrade Pinecone SDK pip install pinecone --upgrade ``` ```shell JavaScript theme={null} # Upgrade Pinecone SDK npm install @pinecone-database/pinecone@latest ``` Also, note that some third-party tutorials and examples still reference the older initialization method. In such cases, follow the example above and the examples throughout the Pinecone documentation instead. # Pinecone Database limits Source: https://docs.pinecone.io/reference/api/database-limits Reference for Pinecone Database limits, covering upsert, query, fetch, delete, import, namespace, and rate limits for serverless indexes. This page describes different types of limits for Pinecone Database. **Looking for a specific limit?** * To compare monthly included usage by plan, start with [read units](#read-units-per-month-per-org), [write units](#write-units-per-month-per-org), and [model usage limits](#monthly-usage-limits). * If you received a `429` error, check [rate limits](#rate-limits), especially request-per-second limits for query, upsert, update, delete, fetch, and list. * For projects, users, indexes, namespaces, storage, backups, and collections, see [object limits](#object-limits). * For batch sizes, metadata filters, and identifier lengths, see [operation limits](#operation-limits) and [identifier limits](#identifier-limits). ## Rate limits Rate limits help protect your applications from misuse and maintain the health of our shared serverless infrastructure. These limits are designed to support typical production workloads while ensuring reliable performance for all users. **Most rate limits can be adjusted upon request.** If you need higher limits to scale your application, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. Pinecone is committed to supporting your growth and can often accommodate higher throughput requirements. Rate limits vary based on [pricing plan](https://www.pinecone.io/pricing/) and apply to [serverless indexes](/guides/index-data/indexing-overview) only. Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Data plane operations: request-per-second limits Pinecone enforces rate limits on the number of API requests per second at the namespace level for data plane operations (query, upsert, delete, and update). These limits provide protection against excessive request rates. #### Affected operations The following operations are subject to request-per-second rate limiting: | Operation | Scope | Limit | | --------- | ------------- | ----- | | Query | Per namespace | 100 | | Upsert | Per namespace | 100 | | Delete | Per namespace | 100 | | Update | Per namespace | 100 | #### Error response When you exceed the request-per-second limit, you'll receive an HTTP `429 - TOO_MANY_REQUESTS` response. The error message indicates which operation exceeded the limit and includes the namespace name and limit value. See the individual limit sections below for specific error message formats. #### How request-per-second limits work with limits on read and write units Request-per-second limits are enforced in addition to existing read unit and write unit limits. Requests must not exceed any applicable limits: * Index-level limits - read and write unit limits, per index * Namespace-level limits - read and write unit limits, per namespace * Request-per-second limits - requests per second, per namespace If any limit is exceeded, the request fails with a 429 error. #### Recommendations If you're hitting request-per-second limits: 1. Implement retry logic. Use exponential backoff to handle rate limit errors gracefully. See [Error Handling Guide](/guides/production/error-handling#implement-retry-logic). 2. Pace your requests. Add client-side rate limiting to stay under limits. 3. Consider [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes), which don't have request-per-second limits and provide dedicated capacity for high-throughput workloads. 4. If you need higher limits, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. ### All rate limits #### Monthly usage limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :---------------------------------------------------------------------------- | :------------- | :------------- | :------------- | :-------------- | | [Read units per month per org](#read-units-per-month-per-org) | 1,000,000 | 2,000,000 | Unlimited | Unlimited | | [Write units per month per org](#write-units-per-month-per-org) | 2,000,000 | 5,000,000 | Unlimited | Unlimited | | [Embedding tokens per month per model](#embedding-tokens-per-month-per-model) | 5,000,000 | 10,000,000 | Unlimited | Unlimited | | [Rerank requests per month per model](#rerank-requests-per-month-per-model) | Model-specific | Model-specific | Model-specific | Model-specific | #### Data operation throughput limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :------------------------------------------------------------------------------------------------------------ | :----------- | :----------- | :------------ | :-------------- | | [Upsert size per second per namespace](#upsert-size-per-second-per-namespace) | 50 MB | 50 MB | 50 MB | 50 MB | | [Query read units per second per index](#query-read-units-per-second-per-index) | 2,000 | 2,000 | 2,000 | 2,000 | | [Query requests per second per namespace](#query-requests-per-second-per-namespace) | 100 | 100 | 100 | 100 | | [Update records per second per namespace](#update-records-per-second-per-namespace) | 100 | 100 | 100 | 100 | | [Update requests per second per namespace](#update-requests-per-second-per-namespace) | 100 | 100 | 100 | 100 | | [Update by metadata requests per second per namespace](#update-by-metadata-requests-per-second-per-namespace) | 5 | 5 | 5 | 5 | | [Update by metadata requests per second per index](#update-by-metadata-requests-per-second-per-index) | 500 | 500 | 500 | 500 | | [Upsert requests per second per namespace](#upsert-requests-per-second-per-namespace) | 100 | 100 | 100 | 100 | | [Fetch requests per second per index](#fetch-requests-per-second-per-index) | 100 | 100 | 100 | 100 | | [List requests per second per index](#list-requests-per-second-per-index) | 200 | 200 | 200 | 200 | | [Describe index stats requests per second per index](#describe-index-stats-requests-per-second-per-index) | 100 | 100 | 100 | 100 | | [Delete requests per second per namespace](#delete-requests-per-second-per-namespace) | 100 | 100 | 100 | 100 | | [Delete records per second per namespace](#delete-records-per-second-per-namespace) | 5,000 | 5,000 | 5,000 | 5,000 | | [Delete records per second per index](#delete-records-per-second-per-index) | 5,000 | 5,000 | 5,000 | 5,000 | | [Delete by metadata requests per second per namespace](#delete-by-metadata-requests-per-second-per-namespace) | 5 | 5 | 5 | 5 | | [Delete by metadata requests per second per index](#delete-by-metadata-requests-per-second-per-index) | 500 | 500 | 500 | 500 | #### Model throughput limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :------------------------------------------------------------------------------ | :------------- | :------------- | :------------- | :-------------- | | [Embedding tokens per minute per model](#embedding-tokens-per-minute-per-model) | Model-specific | Model-specific | Model-specific | Model-specific | | [Rerank requests per minute per model](#rerank-requests-per-minute-per-model) | Model-specific | Model-specific | Model-specific | Model-specific | ### Read units per month per org | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 1,000,000 | 2,000,000 | Unlimited | Unlimited | [Read units](/guides/manage-cost/understanding-cost#read-units) measure the compute, I/O, and network resources used by [fetch](/guides/manage-data/fetch-data), [query](/guides/search/search-overview), and [list](/guides/manage-data/list-record-ids) requests to serverless indexes. When you reach the monthly read unit limit for an organization, fetch, query, and list requests to serverless indexes in the organization will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached your read unit limit for the current month limit. To continue reading data, upgrade your plan. ``` To continue reading from serverless indexes in the organization, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). To check how close you are to the monthly read unit limit for your organization, do the following: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select the project. 3. Select any index in the project. 4. Look under **Usage**. Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Write units per month per org | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 2,000,000 | 5,000,000 | Unlimited | Unlimited | [Write units](/guides/manage-cost/understanding-cost#write-units) measure the storage and compute resources used by [upsert](/guides/index-data/upsert-data), [update](/guides/manage-data/update-data), and [delete](/guides/manage-data/delete-data) requests to serverless indexes. When you reach the monthly write unit limit for an organization, upsert, update, and delete requests to serverless indexes in the organization will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached your write unit limit for the current month. To continue writing data, upgrade your plan. ``` To continue writing data to serverless indexes in the organization, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). To check how close you are to the monthly write unit limit for your organization, do the following: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select the project. 3. Select any index in the project. 4. Look under **Usage**. ### Upsert size per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 50 MB | 50 MB | 50 MB | 50 MB | When you reach the per second [upsert](/guides/index-data/upsert-data) size for a namespace in an index, additional upserts will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max upsert size limit per second for index . Pace your upserts or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Query read units per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 2,000 | 2,000 | 2,000 | 2,000 | Pinecone measures [query](/guides/search/search-overview) usage in [read units](/guides/manage-cost/understanding-cost#read-units). When you reach the per second limit for queries across all namespaces in an index, additional queries will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max query read units per second for index . Pace your queries or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). To check how many read units a query consumes, [check the query response](/guides/manage-cost/monitor-usage-and-costs#read-units). Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Query requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [query](/guides/search/search-overview) limit for a namespace in an index, additional queries will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the query QPS limit for namespace {namespace_name} ({limit} QPS). Pace your queries, consider Dedicated Read Nodes for your index, or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Update records per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [update](/guides/manage-data/update-data) limit for a namespace in an index, additional updates will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max update records per second for namespace . Pace your update requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Update requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [update](/guides/manage-data/update-data) request limit for a namespace in an index, additional update requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the update QPS limit for namespace {namespace_name} ({limit} QPS). Pace your update requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). If you need to update most of the records in a large namespace, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) for help creating an export to enable a faster and more cost-effective approach. ### Update by metadata requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5 | 5 | 5 | 5 | When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit for a namespace in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max update by metadata requests per second for namespace . Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Update by metadata requests per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 500 | 500 | 500 | 500 | When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit across all namespaces in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max update by metadata requests per second for index . Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Upsert requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [upsert](/guides/index-data/upsert-data) request limit for a namespace in an index, additional upsert requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the upsert QPS limit for namespace {namespace_name} ({limit} QPS). Pace your upsert requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Fetch requests per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [fetch](/guides/manage-data/fetch-data) limit across all namespaces in an index, additional fetch requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max fetch requests per second for index . Pace your fetch requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### List requests per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 200 | 200 | 200 | 200 | When you reach the per second [list](/guides/manage-data/list-record-ids) limit across all namespaces in an index, additional list requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max list requests per second for index . Pace your list requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Describe index stats requests per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [describe index stats](/reference/api/2024-10/data-plane/describeindexstats) limit across all namespaces in an index, additional describe index stats requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max describe_index_stats requests per second for index . Pace your describe_index_stats requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [delete](/guides/manage-data/delete-data) request limit for a namespace in an index, additional delete requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the delete QPS limit for namespace {namespace_name} ({limit} QPS). Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete records per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5000 | 5000 | 5000 | 5000 | When you reach the per second [delete](/guides/manage-data/delete-data) limit for a namespace in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete records per second for namespace . Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete records per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5000 | 5000 | 5000 | 5000 | When you reach the per second [delete](/guides/manage-data/delete-data) limit across all namespaces in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete records per second for index . Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete by metadata requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5 | 5 | 5 | 5 | When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit for a namespace in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete by metadata requests per second for namespace . Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete by metadata requests per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 500 | 500 | 500 | 500 | When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit across all namespaces in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete by metadata requests per second for index . Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Embedding tokens per minute per model | Embedding model | Input type | Starter plan | Builder plan | Standard plan | Enterprise plan | | :--------------------------- | :--------- | :----------- | :----------- | :------------ | :-------------- | | `llama-text-embed-v2` | Passage | 250,000 | 250,000 | 1,000,000 | 1,000,000 | | | Query | 50,000 | 50,000 | 250,000 | 250,000 | | `multilingual-e5-large` | Passage | 250,000 | 250,000 | 1,000,000 | 1,000,000 | | | Query | 50,000 | 50,000 | 250,000 | 250,000 | | `pinecone-sparse-english-v0` | Passage | 250,000 | 250,000 | 3,000,000 | 3,000,000 | | | Query | 250,000 | 250,000 | 3,000,000 | 3,000,000 | When you reach the per minute token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max embedding tokens per minute () model ''' and input type '' for the current project. To increase this limit, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). Otherwise, you can handle this limit by [implementing retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). ### Embedding tokens per month per model | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5,000,000 | 10,000,000 | Unlimited | Unlimited | When you reach the monthly token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the embedding token limit () for model for the current month. To continue using this model, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Rerank requests per minute per model | Reranking model | Starter plan | Builder plan | Standard plan | Enterprise plan | | :--------------------- | :------------ | :------------ | :------------ | :-------------- | | `cohere-rerank-4-fast` | Not available | Not available | 300 | 300 | | `cohere-rerank-3.5` | Not available | Not available | 300 | 300 | | `bge-reranker-v2-m3` | 60 | 60 | 60 | 60 | | `pinecone-rerank-v0` | 60 | Not available | 60 | 60 | When you reach the per minute request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max rerank requests per minute () for model '' for the current project. To increase this limit, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Rerank requests per month per model | Reranking model | Starter plan | Builder plan | Standard plan | Enterprise plan | | :--------------------- | :------------ | :------------ | :------------ | :-------------- | | `cohere-rerank-4-fast` | Not available | Not available | Unlimited | Unlimited | | `cohere-rerank-3.5` | Not available | Not available | Unlimited | Unlimited | | `bge-reranker-v2-m3` | 500 | 1,000 | Unlimited | Unlimited | | `pinecone-rerank-v0` | 500 | Not available | Unlimited | Unlimited | When you reach the monthly request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the rerank request limit () for model for the current month. To continue using this model, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Inference requests per second or minute, per project | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :---------------------------- | :----------- | :----------- | :------------ | :-------------- | | Inference requests per second | 100 | 100 | 100 | 100 | | Inference requests per minute | 2000 | 2000 | 2000 | 2000 | When you reach the per second or per minute request limit, inference requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max inference requests per second () for the current project. ``` This error indicates per second or per minute, as applicable. To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). ## Object limits Object limits are restrictions on the number or size of objects in Pinecone. Object limits vary based on [pricing plan](https://www.pinecone.io/pricing/). | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :----------------------------------------------------------------------------- | :----------- | :----------- | :------------ | :-------------- | | [Projects per organization](#projects-per-organization) | 1 | 5 | 20 | 100 | | [Users per organization](#users-per-organization) | 2 | 5 | Unlimited | Unlimited | | [Serverless indexes per project](#serverless-indexes-per-project) 1 | 5 | 10 | 20 | 200 | | [Serverless index storage per org](#serverless-index-storage-per-org) | 2 GB | 10 GB | N/A | N/A | | [Namespaces per serverless index](#namespaces-per-serverless-index) | 100 | 1,000 | 100,000 | 100,000 | | [Serverless backups per project](#serverless-backups-per-project) | N/A | N/A | 500 | 1000 | | [Collections per project](#collections-per-project) | 100 | N/A | N/A | N/A | 1 On the Starter plan, all serverless indexes must be in the `us-east-1` region of AWS. Builder, Standard, and Enterprise plans can create indexes in any [supported region](/guides/index-data/create-an-index#cloud-regions).
### Projects per organization | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 1 | 5 | 20 | 100 | When you reach this quota for an organization, trying to [create projects](/guides/projects/create-a-project) will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max projects allowed in organization . To add more projects, upgrade your plan. ``` To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Users per organization | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 2 | 5 | Unlimited | Unlimited | When you reach this quota for an organization, trying to add users to the organization will fail. To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Serverless indexes per project | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5 | 10 | 20 | 200 | When you reach this quota for a project, trying to [create serverless indexes](/guides/index-data/create-an-index#create-a-serverless-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max serverless indexes allowed in project . Use namespaces to partition your data into logical groups, or upgrade your plan to add more serverless indexes. ``` To stay under this quota, consider using [namespaces](/guides/index-data/create-an-index#namespaces) instead of creating multiple indexes. Namespaces let you partition your data into logical groups within a single index. This approach not only helps you stay within index limits, but can also improve query performance and lower costs by limiting searches to relevant data subsets. To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Serverless index storage per org This limit applies to organizations on the Starter and Builder plans only. | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 2 GB | 10 GB | N/A | N/A | When you've reached this quota for an organization, updates and upserts into serverless indexes will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max storage allowed for organization . To update or upsert new data, delete records or upgrade your plan. ``` To continue writing data into your serverless indexes, [delete records](/guides/manage-data/delete-data) to bring your organization under the limit or [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Namespaces per serverless index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 1,000 | 100,000 | 100,000 | When you reach this quota for a serverless index, trying to [upsert records into a new namespace](/guides/index-data/upsert-data) in the index will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max namespaces allowed in serverless index . To add more namespaces, upgrade your plan. ``` To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). [Namespaces per serverless index](/reference/api/database-limits#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](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Serverless backups per project | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | N/A | N/A | 500 | 1000 | Backups are not available on the Starter or Builder plans. On the Standard and Enterprise plans, when you reach this quota for a project, trying to [create serverless backups](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Backup failed to create. Quota for number of backups per index exceeded. ``` ### Collections per project | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | N/A | N/A | N/A | When you reach this quota for a project, trying to [create collections](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max collections allowed in project . To add more collections, upgrade your plan. ``` To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ## Operation limits Operation limits are restrictions on the size, number, or other characteristics of operations in Pinecone. Operation limits are fixed and do not vary based on pricing plan. ### Upsert limits | Metric | Limit | | :----------------------------------------------------------------- | :------------------------------------------------------------ | | Max [batch size](/guides/index-data/upsert-data#upsert-in-batches) | 2 MB or 1000 records with vectors
96 records with text | | Max documents per upsert request | 1000 | | Max document upsert request size | 2 MB | | Max document size | 2 MB | | Max `full_text_search` string fields per schema | 100 | | Max size per `full_text_search` string field | 100 KB | | Max tokens per `full_text_search` string field | 10,000 | | Max bytes per token | 256 bytes | | Max filterable metadata size per document | 40 KB | | Max length for a record ID | 512 characters | | Max dimensionality for dense vectors | 20,000 | | Max non-zero values for sparse vectors | 2048 | | Max dimensionality for sparse vectors | 4.2 billion | The 40 KB filterable metadata limit does not apply to `full_text_search` text fields. ### Import limits If your import exceeds these limits, you'll get an error specifying the limit exceeded. See [Troubleshooting](/guides/index-data/import-data#troubleshooting) for details. | Metric | Limit | | :-------------------------------------------- | :-------- | | Max namespaces per import | 10,000 | | Max total input data size (on-demand indexes) | 1 TB | | Max total input data size (DRN indexes) | Unlimited | | Max files per import | 100,000 | | Max size per file | 10 GB | The total input data size limit does not apply to indexes with [dedicated read nodes](/guides/index-data/dedicated-read-nodes). Bulk import supports indexes without a schema definition (Parquet files) and indexes with document schemas ([JSONL files](/guides/search/full-text-search#bulk-import)). Semantic-text (auto-embedded) fields are not yet supported in document schemas. ### Query limits | Metric | Limit | | :---------------- | :----- | | Max `top_k` value | 10,000 | | Max result size | 4MB | The query result size is affected by the dimension of the dense vectors and whether or not dense vector values and metadata are included in the result. If a query fails due to exceeding the 4MB result size limit, choose a lower `top_k` value, or use `include_metadata=False` or `include_values=False` to exclude metadata or values from the result. For better performance, especially with higher `top_k` values, avoid including vector values unless you need them. ### Fetch limits **Fetch by ID limits:** | Metric | Limit | | :------------------------------- | :---- | | Max record IDs per fetch request | 1,000 | **Fetch by metadata limits:** | Metric | Limit | | :----------------------- | :---------------------------------- | | Max records per response | 10,000 | | Max response size | 4 MB | | Max request rate | 5 requests per second per namespace | To retrieve more than 10,000 matching records, paginate through results using the `paginationToken` parameter. See [Fetch records by metadata](/guides/manage-data/fetch-data#fetch-records-by-metadata). ### Delete limits | Metric | Limit | | :-------------------------------- | :---- | | Max record IDs per delete request | 1,000 | ### Metadata filter limits The following limits apply to [metadata filter expressions](/guides/search/filter-by-metadata#metadata-filter-expressions) used in query, delete, update, and fetch operations. | Limit | Value | Description | | :------------------------------------------ | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Maximum values per `$in` or `$nin` operator | 10,000 | Each `$in` or `$nin` operator accepts up to 10,000 values in its array. This limit applies per operator—if you have multiple `$in` operators in a single filter, each is independently limited to 10,000 values. | When you exceed this limit, the request will fail and return a `400 - BAD_REQUEST` error. #### Rationale Large `$in` operators can impact query performance and cost. Filters with thousands of values increase request payload size and end-to-end latency. Additionally, using large filters typically indicates a shared namespace architecture, which increases query costs—queries scan the entire namespace regardless of filters. #### Alternative approaches If you need to filter by more than 10,000 values, consider these alternatives: * **Use namespaces for tenant isolation**: Instead of filtering by tenant IDs within a single namespace, create separate namespaces for each tenant or tenant group. This can also reduce query costs. See [Design for multi-tenancy](/guides/index-data/data-modeling#design-for-multi-tenancy). * **Use broader access control groups**: Instead of filtering by individual user IDs, filter by organization, project, or role. This reduces the number of values in your `$in` filter. See [Design for multi-tenancy](/guides/index-data/data-modeling#use-access-control-groups-instead-of-individual-ids). * **Post-filter client-side**: Retrieve a larger top K without filtering (for example, top 1000), then filter results client-side. * **Run multiple queries**: Split your filter into multiple queries with smaller `$in` operators and combine the results client-side. To avoid hitting this limit in production, validate the size of your `$in` and `$nin` arrays in your application code before making the request to Pinecone. ## Identifier limits An identifier is a string of characters used to identify "named" [objects in Pinecone](/guides/get-started/concepts). The following Pinecone objects use strings as identifiers: | Object | Field | Max # characters | Allowed characters | | --------------------------------------------------------- | ----------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | [Organization](/guides/get-started/concepts#organization) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Project](/guides/get-started/concepts#project) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Index](/guides/get-started/concepts#index) | `name` | 45 |
  • `a-z`, `0-9`, and `-`
  • Must be lowercase
  • Cannot start or end with `-`
  • Cannot be empty
| | [Namespace](/guides/get-started/concepts#namespace) | `namespace` | 512 |
  • ASCII except `\0`
  • For the default namespace, use `""` (or `"__default__"`, in API versions `2025-04` and later)
| | [Record](/guides/get-started/concepts#record) | `id` | 512 |
  • ASCII except `\0`
  • Cannot be empty
| # Errors Source: https://docs.pinecone.io/reference/api/errors Pinecone REST API: Pinecone uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the range. Pinecone uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that failed given the information provided, and codes in the `5xx` range indicate an error with Pinecone's servers. For guidance on handling errors in production, see [Error handling](/guides/production/error-handling). ## 200 - OK The request succeeded. ## 201 - CREATED The request succeeded and a new resource was created. ## 202 - NO CONTENT The request succeeded, but there is no content to return. ## 400 - INVALID ARGUMENT The request failed due to an invalid argument. ## 401 - UNAUTHENTICATED The request failed due to a missing or invalid [API key](/guides/projects/understanding-projects#api-keys). ## 402 - PAYMENT REQUIRED The request failed due to delinquent payment or account deactivation for non-payment. See [Account deactivation for non-payment](/guides/organizations/manage-billing/non-payment-account-deactivation). ## 403 - FORBIDDEN The request failed due to an exceeded [quota](/reference/api/database-limits#object-limits) or [index deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection). ## 404 - NOT FOUND The request failed because the resource was not found. ## 409 - ALREADY EXISTS The request failed because the resource already exists. ## 412 - FAILED PRECONDITIONS The request failed due to preconditions not being met. | ## 422 - UNPROCESSABLE ENTITY The request failed because the server was unable to process the contained instructions. ## 429 - TOO MANY REQUESTS The request was [rate-limited](/reference/api/database-limits#rate-limits). [Implement retry logic with exponential backoff](/guides/production/error-handling#handle-rate-limits-429) to handle this error. ## 500 - UNKNOWN An internal server error occurred. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. ## 502 - BAD GATEWAY The API gateway received an invalid response from a backend service. This is typically a temporary error. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. ## 503 - UNAVAILABLE The server is currently unavailable. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. ## 504 - GATEWAY TIMEOUT The API gateway did not receive a timely response from the backend server. This can occur due to slow requests or backend processing delays. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. # API reference Source: https://docs.pinecone.io/reference/api/introduction Pinecone API reference overview for Database, Inference, and Admin endpoints with supported SDKs including Python, Node.js, Java, and Go. Pinecone's APIs let you interact programmatically with your Pinecone account. [SDK versions](/reference/pinecone-sdks#sdk-versions) are pinned to specific API versions. ## Database Use the Database API to store and query records in [Pinecone Database](/guides/get-started/quickstart). The following Pinecone SDKs support the Database API: ## Inference Use the Inference API to generate vector embeddings and rerank results using [embedding models](/guides/index-data/create-an-index#embedding-models) and [reranking models](/guides/search/rerank-results#reranking-models) hosted on Pinecone's infrastructure. There are two ways to use the Inference API: * As a standalone service, through the [Rerank documents](/reference/api/latest/inference/rerank) and [Generate vectors](/reference/api/latest/inference/generate-embeddings) endpoints. * As an integrated part of database operations, through the [Create an index with integrated embedding](/reference/api/latest/control-plane/create_for_model), [Upsert text](/reference/api/latest/data-plane/upsert_records), and [Search with text](/reference/api/latest/data-plane/search_records) endpoints. The following Pinecone SDKs support using the Inference API: # Known limitations Source: https://docs.pinecone.io/reference/api/known-limitations Known limitations and feature restrictions for Pinecone indexes, including upsert consistency, metadata rules, and serverless caveats. This page describes known limitations and feature restrictions in Pinecone. ## General * [Upserts](/guides/index-data/upsert-data) * Pinecone is eventually consistent, so there can be a slight delay before upserted records are available to query. After upserting records, use the [`describe_index_stats`](/reference/api/2024-10/data-plane/describeindexstats) operation to check if the current vector count matches the number of records you expect, although this method may not work for pod-based indexes with multiple replicas. * Only indexes using the [dotproduct distance metric](/guides/index-data/indexing-overview#dotproduct) support querying sparse-dense vectors. Upserting, updating, and fetching sparse-dense vectors in indexes with a different distance metric will succeed, but querying will return an error. * Indexes created before February 22, 2023 do not support sparse vectors. * [Metadata](/guides/index-data/upsert-data#upsert-with-metadata-filters) * Null metadata values aren't supported. Instead of setting a key to `null`, remove the key from the metadata payload. * Nested JSON objects are not supported. ## Serverless indexes Serverless indexes do not support the following features: * [Filtering index statistics by metadata](/reference/api/2024-10/data-plane/describeindexstats) * [Private endpoints](/guides/production/configure-private-endpoints) * This feature is available on AWS only. # API versioning Source: https://docs.pinecone.io/reference/api/versioning Pinecone REST API: Pinecone's APIs are versioned to ensure that your applications continue to work as expected as the platform evolves. Pinecone's APIs are versioned to ensure that your applications continue to work as expected as the platform evolves. Versions are named by release date in the format `YYYY-MM`, for example, `2025-10`. ## Release schedule On a quarterly basis, Pinecone releases a new **stable** API version as well as a **release candidate** of the next stable version. * **Stable:** Each stable version remains unchanged and supported for a minimum of 12 months. Since stable versions are released every 3 months, this means you have at least 9 months to test and migrate your app to the newest stable version before support for the previous version is removed. * **Release candidate:** The release candidate gives you insight into the upcoming changes in the next stable version. It is available for approximately 3 months before the release of the stable version and can include new features, improvements, and [breaking changes](#breaking-changes). Below is an example of Pinecone's release schedule: ## Specify an API version When using the API directly, it is important to specify an API version in your requests. If you don't, requests default to the oldest supported stable version. Once support for that version ends, your requests will default to the next oldest stable version, which could include breaking changes that require you to update your integration. To specify an API version, set the `X-Pinecone-Api-Version` header to the version name. For example, to use the latest stable version (`2026-04`) to describe an index, set the `X-Pinecone-Api-Version` header: ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/indexes/movie-recommendations" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" ``` To use an older version, specify that version instead. ## SDK versions Official [Pinecone SDKs](/reference/pinecone-sdks) provide convenient access to Pinecone APIs. SDK versions are pinned to specific API versions. When a new API version is released, a new version of the SDK is also released. For the mapping between SDK and API versions, see [SDK versions](/reference/pinecone-sdks#sdk-versions). ## Breaking changes Breaking changes are changes that can potentially break your integration with a Pinecone API. Breaking changes include: * Removing an entire operation * Removing or renaming a parameter * Removing or renaming a response field * Adding a new required parameter * Making a previously optional parameter required * Changing the type of a parameter or response field * Removing enum values * Adding a new validation rule to an existing parameter * Changing authentication or authorization requirements ## Non-breaking changes Non-breaking changes are additive and should not break your integration. Additive changes include: * Adding an operation * Adding an optional parameter * Adding an optional request header * Adding a response field * Adding a response header * Adding enum values ## Get updates To ensure you always know about upcoming API changes, follow the [Release notes](/release-notes/). # Create an API key Source: https://docs.pinecone.io/reference/api/2026-04/admin/create_api_key https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/projects/{project_id}/api-keys Create an API key for a project to authenticate Data Plane and Control Plane requests. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const apiKey = await admin.apiKeys.create('YOUR_PROJECT_ID', { name: 'Example API Key', roles: ['ProjectEditor'], }); // `apiKey.value` is returned only at creation time and cannot be retrieved // later. Store it securely and never log it. console.log(apiKey.key); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } roles := []string{"ProjectEditor"} apiKey, err := adminClient.APIKey.Create(ctx, "YOUR_PROJECT_ID", &pinecone.CreateAPIKeyParams{ Name: "Example API Key", Roles: &roles, }) if err != nil { log.Fatalf("Failed to create API key: %v", err) } // Value is returned only at creation time — store it securely and never log it fmt.Printf("Successfully created API key: %v\n", apiKey.Key.Id) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later resource "pinecone_api_key" "example" { name = "Example API Key" project_id = "YOUR_PROJECT_ID" roles = ["ProjectEditor"] } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_PROJECT_ID="YOUR_PROJECT_ID" curl "https://api.pinecone.io/admin/projects/$PINECONE_PROJECT_ID/api-keys" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -d '{ "name": "Example API Key", "roles": ["ProjectEditor"] }' ``` ```json curl theme={null} { "key": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Example API key", "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "roles": [ "ProjectEditor" ] }, "value": "string" } ``` # Invite a user to the organization Source: https://docs.pinecone.io/reference/api/2026-04/admin/create_invite https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/invites Invite a user to the organization by email and grant their initial role bindings. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const invite = await admin.invites.create({ email: 'newhire@example.com', roleBindings: [ { resourceType: 'organization', role: 'OrgMember' }, { resourceType: 'project', resourceId: 'a2f7dddb-1597-4eff-9f71-535fde243f58', role: 'ProjectMember', }, ], }); console.log(invite); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } projectId := "a2f7dddb-1597-4eff-9f71-535fde243f58" invite, err := adminClient.Invite.Create(ctx, &pinecone.CreateInviteParams{ Email: "newhire@example.com", RoleBindings: []pinecone.RoleBindingInput{ {ResourceType: pinecone.ResourceTypeOrganization, Role: "OrgMember"}, {ResourceType: pinecone.ResourceTypeProject, ResourceId: &projectId, Role: "ProjectMember"}, }, }) if err != nil { log.Fatalf("Failed to create invite: %v", err) } fmt.Printf("Invited %v (status: %v)\n", invite.Email, invite.Status) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later resource "pinecone_invite" "newhire" { email = "newhire@example.com" role_bindings = [ { resource_type = "organization" role = "OrgMember" }, { resource_type = "project" resource_id = "a2f7dddb-1597-4eff-9f71-535fde243f58" role = "ProjectMember" } ] } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl "https://api.pinecone.io/admin/invites" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -d '{ "email": "newhire@example.com", "role_bindings": [ { "resource_type": "organization", "role": "OrgMember" }, { "resource_type": "project", "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58", "role": "ProjectMember" } ] }' ``` ```json curl theme={null} { "id": "9c8e3528-b9c0-4358-84ce-84c28e91b566", "email": "newhire@example.com", "status": "pending", "expires_at": "2026-05-21T03:00:00Z", "processed_at": null, "created_at": "2026-04-14T20:00:00Z" } ``` # Create a new project Source: https://docs.pinecone.io/reference/api/2026-04/admin/create_project https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/projects Create a new project. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const project = await admin.projects.create({ name: 'example-project' }); console.log(project); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } project, err := adminClient.Project.Create(ctx, &pinecone.CreateProjectParams{ Name: "example-project", }) if err != nil { log.Fatalf("Failed to create project: %v", err) } fmt.Printf("Successfully created project: %v\n", project.Id) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later resource "pinecone_project" "example" { name = "example-project" } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl "https://api.pinecone.io/admin/projects" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -d '{ "name":"example-project" }' ``` ```json curl theme={null} { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "example-project", "max_pods": 0, "force_encryption_with_cmek": false, "organization_id": "string", "created_at": "2025-03-16T22:46:45.030Z" } ``` # Create a role binding Source: https://docs.pinecone.io/reference/api/2026-04/admin/create_role_binding https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/role-bindings Grant a role to a principal at an organization or project scope. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const roleBinding = await admin.roleBindings.create({ principalType: 'service_account', principalId: 'f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c', resourceType: 'project', resourceId: 'a2f7dddb-1597-4eff-9f71-535fde243f58', role: 'DataPlaneEditor', }); console.log(roleBinding); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } projectId := "a2f7dddb-1597-4eff-9f71-535fde243f58" roleBinding, err := adminClient.RoleBinding.Create(ctx, &pinecone.CreateRoleBindingParams{ PrincipalType: pinecone.PrincipalTypeServiceAccount, PrincipalId: "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c", ResourceType: pinecone.ResourceTypeProject, ResourceId: &projectId, Role: "DataPlaneEditor", }) if err != nil { log.Fatalf("Failed to create role binding: %v", err) } fmt.Printf("Successfully created role binding: %v\n", roleBinding.Id) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # Bindings are immutable; changing any attribute forces replacement resource "pinecone_role_binding" "ci_data_plane_editor" { principal_type = "service_account" principal_id = "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c" resource_type = "project" resource_id = "a2f7dddb-1597-4eff-9f71-535fde243f58" role = "DataPlaneEditor" } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl "https://api.pinecone.io/admin/role-bindings" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -d '{ "principal_type": "service_account", "principal_id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c", "resource_type": "project", "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58", "role": "DataPlaneEditor" }' ``` ```json curl theme={null} { "id": "9a8e3528-b9c0-4358-84ce-84c28e91b566", "principal_type": "service_account", "principal_id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c", "resource_type": "project", "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58", "role": "DataPlaneEditor", "created_at": "2026-04-10T15:23:00Z" } ``` # Create a service account Source: https://docs.pinecone.io/reference/api/2026-04/admin/create_service_account https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/service-accounts Create a service account with optional initial role bindings; the client secret is returned only once. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); // `clientSecret` is returned only once and cannot be retrieved later const { serviceAccount, clientSecret } = await admin.serviceAccounts.create({ name: 'ci-prod', roleBindings: [ { resourceType: 'project', resourceId: 'a2f7dddb-1597-4eff-9f71-535fde243f58', role: 'DataPlaneEditor', }, ], }); console.log(serviceAccount); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } projectId := "a2f7dddb-1597-4eff-9f71-535fde243f58" sa, err := adminClient.ServiceAccount.Create(ctx, &pinecone.CreateServiceAccountParams{ Name: "ci-prod", RoleBindings: []pinecone.RoleBindingInput{ { ResourceType: pinecone.ResourceTypeProject, ResourceId: &projectId, Role: "DataPlaneEditor", }, }, }) if err != nil { log.Fatalf("Failed to create service account: %v", err) } // ClientSecret is returned only once — store it securely and never log it fmt.Printf("Successfully created service account: %v\n", sa.ServiceAccount.Id) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # Roles are assigned with separate pinecone_role_binding resources resource "pinecone_service_account" "ci_prod" { name = "ci-prod" } resource "pinecone_role_binding" "ci_prod_data_plane_editor" { principal_id = pinecone_service_account.ci_prod.id principal_type = "service_account" resource_type = "project" resource_id = "a2f7dddb-1597-4eff-9f71-535fde243f58" role = "DataPlaneEditor" } output "ci_prod_client_secret" { value = pinecone_service_account.ci_prod.client_secret sensitive = true } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl "https://api.pinecone.io/admin/service-accounts" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -d '{ "name": "ci-prod", "role_bindings": [ { "resource_type": "project", "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58", "role": "DataPlaneEditor" } ] }' ``` ```json curl theme={null} { "service_account": { "id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c", "name": "ci-prod", "client_id": "l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn", "created_at": "2026-04-10T15:23:00Z", "updated_at": "2026-04-10T15:23:00Z" }, "client_secret": "8p-kkC23XOWvkCosKq-BOn3G74qp__rBcDMxc82iB4gfzRvuhSCRBKM7C5Q7TAzj" } ``` # Delete an API key Source: https://docs.pinecone.io/reference/api/2026-04/admin/delete_api_key https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/api-keys/{api_key_id} Delete an API key from a project. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); await admin.apiKeys.delete('YOUR_API_KEY_ID'); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } if err := adminClient.APIKey.Delete(ctx, "YOUR_API_KEY_ID"); err != nil { log.Fatalf("Failed to delete API key: %v", err) } } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # This block defines the API key. To delete it, either remove the block and run # `terraform apply`, or run: # terraform destroy -target=pinecone_api_key.example resource "pinecone_api_key" "example" { name = "Example API Key" project_id = "YOUR_PROJECT_ID" } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_API_KEY_ID="YOUR_KEY_ID" curl -X DELETE "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" ``` # Delete an invite Source: https://docs.pinecone.io/reference/api/2026-04/admin/delete_invite https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/invites/{invite_id} Delete a pending or expired invite and its role bindings; to remove an accepted user, delete the user instead. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); await admin.invites.delete('YOUR_INVITE_ID'); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } if err := adminClient.Invite.Delete(ctx, "YOUR_INVITE_ID"); err != nil { log.Fatalf("Failed to delete invite: %v", err) } } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # This block defines the invite. To revoke a pending invite, either remove the # block and run `terraform apply`, or run: # terraform destroy -target=pinecone_invite.newhire resource "pinecone_invite" "newhire" { email = "newhire@example.com" role_bindings = [ { resource_type = "organization" role = "OrgMember" } ] } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_INVITE_ID="YOUR_INVITE_ID" curl -X DELETE "https://api.pinecone.io/admin/invites/$PINECONE_INVITE_ID" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" ``` # Delete a project Source: https://docs.pinecone.io/reference/api/2026-04/admin/delete_project https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/projects/{project_id} Delete a project and all its configuration; delete its indexes, assistants, backups, and collections first. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); await admin.projects.delete('YOUR_PROJECT_ID'); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } if err := adminClient.Project.Delete(ctx, "YOUR_PROJECT_ID"); err != nil { log.Fatalf("Failed to delete project: %v", err) } } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # This block defines the project. To delete it, either remove the block and run # `terraform apply`, or run: # terraform destroy -target=pinecone_project.example resource "pinecone_project" "example" { name = "example-project" } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PROJECT_ID="YOUR_PROJECT_ID" curl -X DELETE "https://api.pinecone.io/admin/projects/$PROJECT_ID" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" ``` # Delete a role binding Source: https://docs.pinecone.io/reference/api/2026-04/admin/delete_role_binding https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/role-bindings/{role_binding_id} Delete a role binding; permissions are revoked when the deletion completes. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); await admin.roleBindings.delete('YOUR_ROLE_BINDING_ID'); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } if err := adminClient.RoleBinding.Delete(ctx, "YOUR_ROLE_BINDING_ID"); err != nil { log.Fatalf("Failed to delete role binding: %v", err) } } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # This block defines the role binding. To revoke the role, either remove the # block and run `terraform apply`, or run: # terraform destroy -target=pinecone_role_binding.ci_data_plane_editor resource "pinecone_role_binding" "ci_data_plane_editor" { principal_type = "service_account" principal_id = "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c" resource_type = "project" resource_id = "a2f7dddb-1597-4eff-9f71-535fde243f58" role = "DataPlaneEditor" } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_ROLE_BINDING_ID="YOUR_ROLE_BINDING_ID" curl -X DELETE "https://api.pinecone.io/admin/role-bindings/$PINECONE_ROLE_BINDING_ID" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" ``` # Delete a service account Source: https://docs.pinecone.io/reference/api/2026-04/admin/delete_service_account https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/service-accounts/{service_account_id} Delete a service account and its role bindings; tokens it minted are revoked within a few seconds. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); await admin.serviceAccounts.delete('YOUR_SERVICE_ACCOUNT_ID'); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } if err := adminClient.ServiceAccount.Delete(ctx, "YOUR_SERVICE_ACCOUNT_ID"); err != nil { log.Fatalf("Failed to delete service account: %v", err) } } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # This block defines the service account. To delete it, either remove the block # and run `terraform apply`, or run: # terraform destroy -target=pinecone_service_account.ci_prod resource "pinecone_service_account" "ci_prod" { name = "ci-prod" } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_SERVICE_ACCOUNT_ID="YOUR_SERVICE_ACCOUNT_ID" curl -X DELETE "https://api.pinecone.io/admin/service-accounts/$PINECONE_SERVICE_ACCOUNT_ID" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" ``` # Remove a user from the organization Source: https://docs.pinecone.io/reference/api/2026-04/admin/delete_user https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/users/{user_id} Remove a user from the organization and revoke their role bindings; their Pinecone account is not deleted. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); await admin.users.delete('YOUR_USER_ID'); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } if err := adminClient.User.Delete(ctx, "YOUR_USER_ID"); err != nil { log.Fatalf("Failed to delete user: %v", err) } } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # Users join by accepting an invite, so import the existing member first: # terraform import pinecone_user.teammate YOUR_USER_ID # Then remove the resource block and run `terraform apply` to remove them # from the organization. resource "pinecone_user" "teammate" { id = "YOUR_USER_ID" } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_USER_ID="YOUR_USER_ID" curl -X DELETE "https://api.pinecone.io/admin/users/$PINECONE_USER_ID" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" ``` # Get API key details Source: https://docs.pinecone.io/reference/api/2026-04/admin/fetch_api_key https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/api-keys/{api_key_id} Get an API key's details, excluding its secret. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const apiKey = await admin.apiKeys.describe('YOUR_API_KEY_ID'); console.log(apiKey); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } apiKey, err := adminClient.APIKey.Describe(ctx, "YOUR_API_KEY_ID") if err != nil { log.Fatalf("Failed to describe API key: %v", err) } fmt.Printf("API key: %v (%v)\n", apiKey.Name, apiKey.Id) } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_API_KEY_ID="3fa85f64-5717-4562-b3fc-2c963f66afa6" curl -X GET "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "accept: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "roles": [ "ProjectEditor" ] } ``` # Get invite details Source: https://docs.pinecone.io/reference/api/2026-04/admin/fetch_invite https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/invites/{invite_id} Get an invite in the caller's organization by ID. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const invite = await admin.invites.describe('YOUR_INVITE_ID'); console.log(invite); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } invite, err := adminClient.Invite.Describe(ctx, "YOUR_INVITE_ID") if err != nil { log.Fatalf("Failed to describe invite: %v", err) } fmt.Printf("Invite: %v (status: %v)\n", invite.Email, invite.Status) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later data "pinecone_invite" "example" { id = "YOUR_INVITE_ID" } output "invite_status" { value = data.pinecone_invite.example.status } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_INVITE_ID="9c8e3528-b9c0-4358-84ce-84c28e91b566" curl -X GET "https://api.pinecone.io/admin/invites/$PINECONE_INVITE_ID" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "accept: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "id": "9c8e3528-b9c0-4358-84ce-84c28e91b566", "email": "newhire@example.com", "status": "pending", "expires_at": "2026-05-21T03:00:00Z", "processed_at": null, "created_at": "2026-04-14T20:00:00Z" } ``` # Get project details Source: https://docs.pinecone.io/reference/api/2026-04/admin/fetch_project https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/projects/{project_id} Get a project's details. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const project = await admin.projects.describe('YOUR_PROJECT_ID'); console.log(project); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } project, err := adminClient.Project.Describe(ctx, "YOUR_PROJECT_ID") if err != nil { log.Fatalf("Failed to describe project: %v", err) } fmt.Printf("Project: %v (%v)\n", project.Name, project.Id) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later data "pinecone_project" "example" { id = "YOUR_PROJECT_ID" } output "project_name" { value = data.pinecone_project.example.name } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PROJECT_ID="3fa85f64-5717-4562-b3fc-2c963f66afa6" curl -X GET "https://api.pinecone.io/admin/projects/$PROJECT_ID" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "accept: application/json" ``` ```json curl theme={null} { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "example-project", "max_pods": 0, "force_encryption_with_cmek": false, "organization_id": "string", "created_at": "2025-03-17T00:30:23.262Z" } ``` # Get role binding details Source: https://docs.pinecone.io/reference/api/2026-04/admin/fetch_role_binding https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/role-bindings/{role_binding_id} Get a role binding in the caller's organization by ID. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const roleBinding = await admin.roleBindings.describe('YOUR_ROLE_BINDING_ID'); console.log(roleBinding); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } roleBinding, err := adminClient.RoleBinding.Describe(ctx, "YOUR_ROLE_BINDING_ID") if err != nil { log.Fatalf("Failed to describe role binding: %v", err) } fmt.Printf("Role binding: %v (%v)\n", roleBinding.Role, roleBinding.Id) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later data "pinecone_role_binding" "example" { id = "YOUR_ROLE_BINDING_ID" } output "role" { value = data.pinecone_role_binding.example.role } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_ROLE_BINDING_ID="9a8e3528-b9c0-4358-84ce-84c28e91b566" curl -X GET "https://api.pinecone.io/admin/role-bindings/$PINECONE_ROLE_BINDING_ID" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "accept: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "id": "9a8e3528-b9c0-4358-84ce-84c28e91b566", "principal_type": "service_account", "principal_id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c", "resource_type": "project", "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58", "role": "DataPlaneEditor", "created_at": "2026-04-10T15:23:00Z" } ``` # Get service account details Source: https://docs.pinecone.io/reference/api/2026-04/admin/fetch_service_account https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/service-accounts/{service_account_id} Get a service account by ID; the client secret is returned only from create and rotate-secret requests. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const serviceAccount = await admin.serviceAccounts.describe('YOUR_SERVICE_ACCOUNT_ID'); console.log(serviceAccount); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } sa, err := adminClient.ServiceAccount.Describe(ctx, "YOUR_SERVICE_ACCOUNT_ID") if err != nil { log.Fatalf("Failed to describe service account: %v", err) } fmt.Printf("Service account: %v (%v)\n", sa.Name, sa.Id) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later data "pinecone_service_account" "example" { id = "YOUR_SERVICE_ACCOUNT_ID" } output "service_account_name" { value = data.pinecone_service_account.example.name } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_SERVICE_ACCOUNT_ID="f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c" curl -X GET "https://api.pinecone.io/admin/service-accounts/$PINECONE_SERVICE_ACCOUNT_ID" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "accept: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c", "name": "My Service Account", "client_id": "l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn", "created_at": "2026-04-10T15:23:00Z", "updated_at": "2026-04-12T09:11:00Z" } ``` # Get user details Source: https://docs.pinecone.io/reference/api/2026-04/admin/fetch_user https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/users/{user_id} Get a user in the caller's organization by ID. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const user = await admin.users.describe('YOUR_USER_ID'); console.log(user); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } user, err := adminClient.User.Describe(ctx, "YOUR_USER_ID") if err != nil { log.Fatalf("Failed to describe user: %v", err) } fmt.Printf("User: %v (%v)\n", user.Email, user.Id) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # Look up a user by id or by email data "pinecone_user" "example" { id = "YOUR_USER_ID" } output "user_name" { value = data.pinecone_user.example.name } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_USER_ID="e2e92523-85dc-4142-b8c2-e681be8b78df" curl -X GET "https://api.pinecone.io/admin/users/$PINECONE_USER_ID" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "accept: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "id": "e2e92523-85dc-4142-b8c2-e681be8b78df", "email": "alice@example.com", "name": "Alice Example", "created_at": "2026-04-10T15:23:00Z", "updated_at": "2026-04-12T09:11:00Z" } ``` # Create an access token Source: https://docs.pinecone.io/reference/api/2026-04/admin/get_token https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/oauth_2026-04.oas.yaml post /oauth/token Obtain an access token for a service account using the OAuth2 client credentials flow. An access token is needed to authorize requests to the Pinecone Admin API. The host domain for OAuth endpoints is `login.pinecone.io`. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // You don't call this endpoint directly when using the SDK. The AdminClient // exchanges your service account credentials for an access token on the first // admin request and reuses it for subsequent calls. const admin = new AdminClient({ clientId: 'YOUR_CLIENT_ID', clientSecret: 'YOUR_CLIENT_SECRET', }); const { data: projects } = await admin.projects.list(); console.log(projects); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() // You don't call this endpoint directly when using the SDK. The AdminClient // exchanges your service account credentials for an access token. adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: "YOUR_CLIENT_ID", ClientSecret: "YOUR_CLIENT_SECRET", }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } projects, err := adminClient.Project.List(ctx) if err != nil { log.Fatalf("Failed to list projects: %v", err) } fmt.Printf("Found %v projects\n", len(projects)) } ``` ```bash curl theme={null} curl "https://login.pinecone.io/oauth/token" \ # Note: Base URL is login.pinecone.io -H "X-Pinecone-Api-Version: 2026-04" \ -H "Content-Type: application/json" \ -d '{ "grant_type": "client_credentials", "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "audience": "https://api.pinecone.io/" }' ``` ```json curl theme={null} { "access_token":"YOUR_ACCESS_TOKEN", "expires_in":86400, "token_type":"Bearer" } ``` # List API keys Source: https://docs.pinecone.io/reference/api/2026-04/admin/list_api_keys https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/projects/{project_id}/api-keys List all API keys in a project. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const { data: apiKeys } = await admin.apiKeys.list('YOUR_PROJECT_ID'); console.log(apiKeys); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } apiKeys, err := adminClient.APIKey.List(ctx, "YOUR_PROJECT_ID") if err != nil { log.Fatalf("Failed to list API keys: %v", err) } for _, apiKey := range apiKeys { fmt.Printf("API key: %v (%v)\n", apiKey.Name, apiKey.Id) } } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_PROJECT_ID="YOUR_PROJECT_ID" curl -X GET "https://api.pinecone.io/admin/projects/$PINECONE_PROJECT_ID/api-keys" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "data": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "roles": [ "ProjectEditor" ] } ] } ``` # List invites Source: https://docs.pinecone.io/reference/api/2026-04/admin/list_invites https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/invites List pending and expired invites in the caller's organization. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const { data: invites } = await admin.invites.list(); console.log(invites); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } invites, err := adminClient.Invite.List(ctx, &pinecone.ListInvitesParams{}) if err != nil { log.Fatalf("Failed to list invites: %v", err) } for _, invite := range invites.Data { fmt.Printf("Invite: %v (status: %v)\n", invite.Email, invite.Status) } } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later data "pinecone_invites" "all" {} output "invite_emails" { value = [for invite in data.pinecone_invites.all.invites : invite.email] } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl -X GET "https://api.pinecone.io/admin/invites" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "accept: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "data": [ { "id": "9c8e3528-b9c0-4358-84ce-84c28e91b566", "email": "newhire@example.com", "status": "pending", "expires_at": "2026-05-21T03:00:00Z", "processed_at": null, "created_at": "2026-04-14T20:00:00Z" } ], "pagination": { "next": "eyJsYXN0X2lkIjoiOWM4ZTM1MjgifQ==" } } ``` # List projects Source: https://docs.pinecone.io/reference/api/2026-04/admin/list_projects https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/projects List all projects in an organization. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const { data: projects } = await admin.projects.list(); console.log(projects); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } projects, err := adminClient.Project.List(ctx) if err != nil { log.Fatalf("Failed to list projects: %v", err) } for _, project := range projects { fmt.Printf("Project: %v (%v)\n", project.Name, project.Id) } } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later data "pinecone_projects" "all" {} output "project_names" { value = [for project in data.pinecone_projects.all.projects : project.name] } ``` ```bash curl theme={null} curl -X GET "https://api.pinecone.io/admin/projects" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "data": [ { "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "name": "example-project", "max_pods": 0, "force_encryption_with_cmek": true, "organization_id": "", "created_at": "2023-11-07T05:31:56Z" } ] } ``` # List role bindings Source: https://docs.pinecone.io/reference/api/2026-04/admin/list_role_bindings https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/role-bindings List role bindings in the caller's organization, optionally filtered by principal, resource, and role. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const { data: roleBindings } = await admin.roleBindings.list({ principalType: 'user', principalId: 'e2e92523-85dc-4142-b8c2-e681be8b78df', }); console.log(roleBindings); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } principalType := pinecone.PrincipalTypeUser principalId := "e2e92523-85dc-4142-b8c2-e681be8b78df" roleBindings, err := adminClient.RoleBinding.List(ctx, &pinecone.ListRoleBindingsParams{ PrincipalType: &principalType, PrincipalId: &principalId, }) if err != nil { log.Fatalf("Failed to list role bindings: %v", err) } for _, roleBinding := range roleBindings.Data { fmt.Printf("Role binding: %v (%v)\n", roleBinding.Role, roleBinding.Id) } } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later data "pinecone_role_bindings" "user_roles" { principal_type = "user" principal_id = "e2e92523-85dc-4142-b8c2-e681be8b78df" } output "user_roles" { value = [for b in data.pinecone_role_bindings.user_roles.role_bindings : b.role] } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl -X GET "https://api.pinecone.io/admin/role-bindings?principal_type=user&principal_id=e2e92523-85dc-4142-b8c2-e681be8b78df" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "accept: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "data": [ { "id": "5a86ed21-daf1-448d-a9ca-f92a0fd839d3", "principal_type": "user", "principal_id": "e2e92523-85dc-4142-b8c2-e681be8b78df", "resource_type": "organization", "resource_id": "-ExampleOrgId0000000", "role": "OrgMember", "created_at": "2026-04-10T15:23:00Z" } ], "pagination": { "next": "eyJsYXN0X2lkIjoiNWE4NmVkMjEifQ==" } } ``` # List service accounts Source: https://docs.pinecone.io/reference/api/2026-04/admin/list_service_accounts https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/service-accounts List service accounts in the caller's organization. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const { data: serviceAccounts } = await admin.serviceAccounts.list(); console.log(serviceAccounts); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } serviceAccounts, err := adminClient.ServiceAccount.List(ctx, &pinecone.ListServiceAccountsParams{}) if err != nil { log.Fatalf("Failed to list service accounts: %v", err) } for _, sa := range serviceAccounts.Data { fmt.Printf("Service account: %v (%v)\n", sa.Name, sa.Id) } } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later data "pinecone_service_accounts" "all" {} output "service_account_names" { value = [for sa in data.pinecone_service_accounts.all.service_accounts : sa.name] } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl -X GET "https://api.pinecone.io/admin/service-accounts" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "accept: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "data": [ { "id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c", "name": "My Service Account", "client_id": "l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn", "created_at": "2026-04-10T15:23:00Z", "updated_at": "2026-04-12T09:11:00Z" } ], "pagination": { "next": "eyJsYXN0X2lkIjoiZDI0MTc3YTAifQ==" } } ``` # List users in the organization Source: https://docs.pinecone.io/reference/api/2026-04/admin/list_users https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/users List users in the caller's organization, optionally filtered by email address. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const { data: users } = await admin.users.list(); console.log(users); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } users, err := adminClient.User.List(ctx, &pinecone.ListUsersParams{}) if err != nil { log.Fatalf("Failed to list users: %v", err) } for _, user := range users.Data { fmt.Printf("User: %v (%v)\n", user.Email, user.Id) } } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later data "pinecone_users" "all" {} output "user_emails" { value = [for user in data.pinecone_users.all.users : user.email] } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl -X GET "https://api.pinecone.io/admin/users" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "accept: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "data": [ { "id": "e2e92523-85dc-4142-b8c2-e681be8b78df", "email": "alice@example.com", "name": "Alice Example", "created_at": "2026-04-10T15:23:00Z", "updated_at": "2026-04-12T09:11:00Z" } ], "pagination": { "next": "eyJsYXN0X2lkIjoiZTJlOTI1MjMifQ==" } } ``` # Resend an invite email Source: https://docs.pinecone.io/reference/api/2026-04/admin/resend_invite https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/invites/{invite_id}/resend Resend the invite email and extend its expiration to 7 days from now; limited to 100 emails per hour per organization. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const invite = await admin.invites.resend('YOUR_INVITE_ID'); console.log(invite); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } invite, err := adminClient.Invite.Resend(ctx, "YOUR_INVITE_ID") if err != nil { log.Fatalf("Failed to resend invite: %v", err) } fmt.Printf("Resent invite to %v (status: %v)\n", invite.Email, invite.Status) } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_INVITE_ID="9c8e3528-b9c0-4358-84ce-84c28e91b566" curl -X POST "https://api.pinecone.io/admin/invites/$PINECONE_INVITE_ID/resend" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" ``` ```json curl theme={null} { "id": "9c8e3528-b9c0-4358-84ce-84c28e91b566", "email": "newhire@example.com", "status": "pending", "expires_at": "2026-05-28T20:14:00Z", "processed_at": null, "created_at": "2026-04-14T20:00:00Z" } ``` # Rotate a service account's OAuth client secret Source: https://docs.pinecone.io/reference/api/2026-04/admin/rotate_service_account_secret https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/service-accounts/{service_account_id}/rotate-secret Rotate a service account's OAuth client secret; the previous secret and its tokens are revoked within seconds and the new secret is returned only once. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); // The previous secret is invalidated, and the new one is returned only once const { serviceAccount, clientSecret } = await admin.serviceAccounts.rotateSecret( 'YOUR_SERVICE_ACCOUNT_ID' ); console.log(serviceAccount); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } sa, err := adminClient.ServiceAccount.RotateSecret(ctx, "YOUR_SERVICE_ACCOUNT_ID") if err != nil { log.Fatalf("Failed to rotate service account secret: %v", err) } // ClientSecret is returned only once — store it securely and never log it fmt.Printf("Successfully rotated secret for service account: %v\n", sa.ServiceAccount.Id) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # Change rotate_trigger to any new value to issue and store a new secret resource "pinecone_service_account" "ci_prod" { name = "ci-prod" rotate_trigger = "2026-04-10" } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_SERVICE_ACCOUNT_ID="f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c" curl -X POST "https://api.pinecone.io/admin/service-accounts/$PINECONE_SERVICE_ACCOUNT_ID/rotate-secret" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" ``` ```json curl theme={null} { "service_account": { "id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c", "name": "My Service Account", "client_id": "l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn", "created_at": "2026-04-10T15:23:00Z", "updated_at": "2026-04-10T15:23:00Z" }, "client_secret": "8p-kkC23XOWvkCosKq-BOn3G74qp__rBcDMxc82iB4gfzRvuhSCRBKM7C5Q7TAzj" } ``` # Update an API key Source: https://docs.pinecone.io/reference/api/2026-04/admin/update_api_key https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml patch /admin/api-keys/{api_key_id} Update an API key's name and roles. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const apiKey = await admin.apiKeys.update('YOUR_API_KEY_ID', { name: 'New API key name', roles: ['ProjectEditor'], }); console.log(apiKey); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } name := "New API key name" roles := []string{"ProjectEditor"} apiKey, err := adminClient.APIKey.Update(ctx, "YOUR_API_KEY_ID", &pinecone.UpdateAPIKeyParams{ Name: &name, Roles: &roles, }) if err != nil { log.Fatalf("Failed to update API key: %v", err) } fmt.Printf("Successfully updated API key: %v\n", apiKey.Name) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # Change the name or roles on an existing resource, then run `terraform apply` resource "pinecone_api_key" "example" { name = "New API key name" project_id = "YOUR_PROJECT_ID" roles = ["ProjectEditor"] } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_API_KEY_ID="YOUR_API_KEY_ID" curl -X PATCH "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -d '{ "name": "New API key name", "roles": ["ProjectEditor"] }' ``` ```json curl theme={null} { "key": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "New API key name", "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "roles": [ "ProjectEditor" ] }, "value": "string" } ``` # Update a project Source: https://docs.pinecone.io/reference/api/2026-04/admin/update_project https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml patch /admin/projects/{project_id} Update a project's name, maximum number of Pods, or customer-managed encryption key (CMEK). ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const project = await admin.projects.update('YOUR_PROJECT_ID', { name: 'updated-example-project', }); console.log(project); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } name := "updated-example-project" project, err := adminClient.Project.Update(ctx, "YOUR_PROJECT_ID", &pinecone.UpdateProjectParams{ Name: &name, }) if err != nil { log.Fatalf("Failed to update project: %v", err) } fmt.Printf("Successfully updated project: %v\n", project.Name) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # Change the name on an existing resource, then run `terraform apply` resource "pinecone_project" "example" { name = "updated-example-project" } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PROJECT_ID="YOUR_PROJECT_ID" curl -X PATCH "https://api.pinecone.io/admin/projects/$PROJECT_ID" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" \ -d '{ "name": "updated-example-project" }' ``` ```json curl theme={null} { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "updated-example-project", "max_pods": 0, "force_encryption_with_cmek": false, "organization_id": "string", "created_at": "2025-03-17T00:42:31.912Z" } ``` # Update a service account Source: https://docs.pinecone.io/reference/api/2026-04/admin/update_service_account https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml patch /admin/service-accounts/{service_account_id} Update a service account's name; role bindings are managed through the role-binding endpoints. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const serviceAccount = await admin.serviceAccounts.update('YOUR_SERVICE_ACCOUNT_ID', { name: 'ci-prod-renamed', }); console.log(serviceAccount); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } name := "ci-prod-renamed" sa, err := adminClient.ServiceAccount.Update(ctx, "YOUR_SERVICE_ACCOUNT_ID", &pinecone.UpdateServiceAccountParams{ Name: &name, }) if err != nil { log.Fatalf("Failed to update service account: %v", err) } fmt.Printf("Successfully updated service account: %v\n", sa.Name) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # Change the name on an existing resource, then run `terraform apply` resource "pinecone_service_account" "ci_prod" { name = "ci-prod-renamed" } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_SERVICE_ACCOUNT_ID="YOUR_SERVICE_ACCOUNT_ID" curl -X PATCH "https://api.pinecone.io/admin/service-accounts/$PINECONE_SERVICE_ACCOUNT_ID" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -d '{ "name": "ci-prod-renamed" }' ``` ```json curl theme={null} { "id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c", "name": "ci-prod-renamed", "client_id": "l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn", "created_at": "2026-04-10T15:23:00Z", "updated_at": "2026-04-12T09:11:00Z" } ``` # Configure an index Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/configure_index https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml patch /indexes/{index_name} Configure an existing index. For guidance and examples, see [Manage indexes](https://docs.pinecone.io/guides/manage-data/manage-indexes). ```shell curl theme={null} # EXAMPLE REQUEST 1: Serverless index (on-demand) # Enable deletion protection and add tags to an # existing on-demand index. PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="YOUR_INDEX_NAME" curl -X PATCH "https://api.pinecone.io/indexes/$INDEX_NAME" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" \ -d '{ "deletion_protection": "enabled", "tags": { "tag1": "value1", "tag2": "value2" } }' # EXAMPLE REQUEST 2: Serverless index (dedicated) # Add a replica to an existing dedicated index. PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="YOUR_INDEX_NAME" curl -X PATCH "https://api.pinecone.io/indexes/$INDEX_NAME" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" \ -d '{ "spec": { "serverless": { "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 2, "replicas": 2 } } } } } }' ``` ```jsonc curl theme={null} // EXAMPLE RESPONSE 1: Serverless index (on-demand) // Enable deletion protection and add tags to an // existing on-demand index. { "name": "example-serverless-ondemand-index", "vector_type": "dense", "metric": "cosine", "dimension": 1024, "status": { "ready": true, "state": "Ready" }, "host": "example-serverless-ondemand-index-bhnyigt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "OnDemand", "status": { "state": "Ready", "current_shards": null, "current_replicas": null } } } }, "deletion_protection": "enabled", "tags": { "tag1": "value1", "tag2": "value2" }, "embed": { "model": "llama-text-embed-v2", "field_map": { "text": "text" }, "dimension": 1024, "metric": "cosine", "write_parameters": { "dimension": 1024, "input_type": "passage", "truncate": "END" }, "read_parameters": { "dimension": 1024, "input_type": "query", "truncate": "END" }, "vector_type": "dense" } } // EXAMPLE RESPONSE 2: Serverless index (dedicated) // Add a replica to an existing dedicated index. { "name": "example-serverless-dedicated-index", "vector_type": "dense", "metric": "cosine", "dimension": 1536, "status": { "ready": true, "state": "Ready" }, "host": "example-serverless-dedicated-index-bhnyigt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 1, "replicas": 2 <-- desired state } }, "status": { "state": "Scaling", "current_shards": 1, "current_replicas": 1 <-- current state } } } }, "deletion_protection": "enabled", "tags": { "tag0": "value0" } } ``` # Create an index with integrated embedding Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/create_for_model https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml post /indexes/create-for-model Create an index with integrated embedding. With this type of index, you provide source text, and Pinecone uses a [hosted embedding model](https://docs.pinecone.io/guides/index-data/create-an-index#embedding-models) to convert the text automatically during [upsert](https://docs.pinecone.io/reference/api/2026-04/data-plane/upsert_records) and [search](https://docs.pinecone.io/reference/api/2026-04/data-plane/search_records). For guidance and examples, see [Create an index](https://docs.pinecone.io/guides/index-data/create-an-index#integrated-embedding). ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl https://api.pinecone.io/indexes/create-for-model \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" \ -d '{ "name": "integrated-dense-curl", "cloud": "aws", "region": "us-east-1", "embed": { "model": "llama-text-embed-v2", "metric": "cosine", "field_map": { "text": "chunk_text" }, "write_parameters": { "input_type": "passage", "truncate": "END" }, "read_parameters": { "input_type": "query", "truncate": "END" } } }' ``` ```json curl theme={null} { "id": "9dabb7cb-ec0a-4e2e-b79e-c7c997e592ce", "name": "integrated-dense-curl", "metric": "cosine", "dimension": 1024, "status": { "ready": false, "state": "Initializing" }, "host": "integrated-dense-curl-govk0nt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws" } }, "deletion_protection": "disabled", "tags": null, "embed": { "model": "llama-text-embed-v2", "field_map": { "text": "chunk_text" }, "dimension": 1024, "metric": "cosine", "write_parameters": { "input_type": "passage", "truncate": "END" }, "read_parameters": { "input_type": "query", "truncate": "END" } } } ``` # Create an index Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/create_index https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml post /indexes Create a Pinecone index. This is where you specify the measure of similarity, the dimension of vectors to be stored in the index, which cloud provider you would like to deploy with, and more. To restore from a backup, set `spec.serverless.source_backup_id` and specify the target `cloud` and `region`. Same-cloud cross-region restore is supported when available for the backup's source region. Cross-cloud restore is not supported. For guidance and examples, see [Create an index](https://docs.pinecone.io/guides/index-data/create-an-index). ## Cloud regions For serverless indexes, the `cloud` and `region` fields in `spec.serverless` accept the following values: | Cloud | Region | [Supported plans](https://www.pinecone.io/pricing/) | [Availability phase](/release-notes/feature-availability) | | ------- | ---------------------------- | --------------------------------------------------- | --------------------------------------------------------- | | `aws` | `us-east-1` (Virginia) | Starter, Builder, Standard, Enterprise | General availability | | `aws` | `us-west-2` (Oregon) | Builder, Standard, Enterprise | General availability | | `aws` | `eu-west-1` (Ireland) | Builder, Standard, Enterprise | General availability | | `aws` | `eu-central-1` (Frankfurt) | Builder, Standard, Enterprise | General availability | | `aws` | `ap-southeast-1` (Singapore) | Builder, Standard, Enterprise | General availability | | `gcp` | `us-central1` (Iowa) | Builder, Standard, Enterprise | General availability | | `gcp` | `europe-west4` (Netherlands) | Builder, Standard, Enterprise | General availability | | `azure` | `eastus2` (Virginia) | Builder, Standard, Enterprise | General availability | The cloud and region cannot be changed after a serverless index is created. On the Starter plan, you can create serverless indexes in the `us-east-1` region of AWS only. To create indexes in other regions, [upgrade to the Builder, Standard, or Enterprise plan](/guides/organizations/manage-billing/upgrade-billing-plan). For BYOC indexes, set `spec.byoc.environment` to the environment ID provisioned for your account instead. See [Bring your own cloud](/guides/production/bring-your-own-cloud) for details. ```shell curl theme={null} # EXAMPLE REQUEST 1: Serverless index (on-demand) PINECONE_API_KEY="YOUR_API_KEY" curl -s "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" \ -d '{ "name": "example-serverless-index", "vector_type": "dense", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "tags": { "tag0": "value0" }, "deletion_protection": "disabled" }' # EXAMPLE REQUEST 2: Serverless index (dedicated) PINECONE_API_KEY="YOUR_API_KEY" curl "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" \ -d '{ "name": "example-serverless-dedicated-index", "dimension": 1536, "metric": "cosine", "deletion_protection": "enabled", "tags": { "tag0": "value0" }, "vector_type": "dense", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 2, "replicas": 1 } } } } } }' # EXAMPLE REQUEST 3: BYOC index PINECONE_API_KEY="YOUR_API_KEY" curl -s "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" \ -d '{ "name": "example-byoc-index", "vector_type": "dense", "dimension": 1536, "metric": "cosine", "spec": { "byoc": { "environment": "aws-us-east-1-b921" } }, "tags": { "tag0": "value0" }, "deletion_protection": "disabled" }' ``` ```jsonc curl theme={null} // EXAMPLE RESPONSE 1: Serverless index (on-demand) { "name": "example-serverless-ondemand-index", "vector_type": "dense", "metric": "cosine", "dimension": 1536, "status": { "ready": false, "state": "Initializing" }, "host": "example-serverless-ondemand-index-bhnyigt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "OnDemand", "status": { "state": "Ready", "current_shards": null, "current_replicas": null } } } }, "deletion_protection": "disabled", "tags": { "tag0": "value0" } } // EXAMPLE RESPONSE 2: Serverless index (dedicated) { "name": "example-serverless-dedicated-index", "vector_type": "dense", "metric": "cosine", "dimension": 1536, "status": { "ready": false, "state": "Initializing" }, "host": "example-serverless-dedicated-index-bhnyigt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 2, "replicas": 1 } }, "status": { "state": "Migrating", "current_shards": null, "current_replicas": null } } } }, "deletion_protection": "enabled", "tags": { "tag0": "value0" } } // EXAMPLE RESPONSE 3: BYOC index { "name": "example-byoc-index", "vector_type": "dense", "metric": "cosine", "dimension": 1536, "status": { "ready": true, "state": "Ready" }, "host": "example-byoc-index-govk0nt.svc.private.aped-4627-b74a.pinecone.io", "spec": { "byoc": { "environment": "aws-us-east-1-b921" } }, "deletion_protection": "disabled", "tags": { "tag0": "value0" } } ``` # Delete an index Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/delete_index https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml delete /indexes/{index_name} Delete an existing index. ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X DELETE "https://api.pinecone.io/indexes/docs-example" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" ``` # Describe an index Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/describe_index https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml get /indexes/{index_name} Get a description of an index. ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="YOUR_INDEX_NAME" curl "https://api.pinecone.io/indexes/$INDEX_NAME" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```jsonc curl theme={null} // EXAMPLE RESPONSE 1: Serverless index (on-demand) { "name": "example-serverless-ondemand-index", "vector_type": "dense", "metric": "cosine", "dimension": 1024, "status": { "ready": true, "state": "Ready" }, "host": "example-serverless-ondemand-index-bhnyigt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "OnDemand", "status": { "state": "Ready", "current_shards": null, "current_replicas": null } } } }, "deletion_protection": "enabled", "tags": { "tag1": "value1", "tag2": "value2" }, "embed": { "model": "llama-text-embed-v2", "field_map": { "text": "text" }, "dimension": 1024, "metric": "cosine", "write_parameters": { "dimension": 1024, "input_type": "passage", "truncate": "END" }, "read_parameters": { "dimension": 1024, "input_type": "query", "truncate": "END" }, "vector_type": "dense" } } // EXAMPLE RESPONSE 2: Serverless index (dedicated) { "name": "example-serverless-dedicated-index", "vector_type": "dense", "metric": "cosine", "dimension": 1536, "status": { "ready": true, "state": "Ready" }, "host": "example-serverless-dedicated-index-bhnyigt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 1, "replicas": 2 } }, "status": { "state": "Scaling", "current_shards": 1, "current_replicas": 1 } } } }, "deletion_protection": "enabled", "tags": { "tag0": "value0", "tag1": "value1" } } ``` # List indexes Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/list_indexes https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml get /indexes List all indexes in a project. ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/indexes" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "indexes": [ { "name": "example-serverless-dedicated-index", "vector_type": "dense", "metric": "cosine", "dimension": 1536, "status": { "ready": true, "state": "Ready" }, "host": "example-serverless-dedicated-index-bhnyigt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 1, "replicas": 2 } }, "status": { "state": "Scaling", "current_shards": 1, "current_replicas": 1 } } } }, "deletion_protection": "enabled", "tags": { "tag0": "value0", "tag1": "value1" } }, { "name": "example-serverless-ondemand-index", "vector_type": "dense", "metric": "cosine", "dimension": 1024, "status": { "ready": true, "state": "Ready" }, "host": "example-serverless-ondemand-index-bhnyigt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "OnDemand", "status": { "state": "Ready", "current_shards": null, "current_replicas": null } } } }, "deletion_protection": "enabled", "tags": { "tag1": "value1", "tag2": "value2" }, "embed": { "model": "llama-text-embed-v2", "field_map": { "text": "text" }, "dimension": 1024, "metric": "cosine", "write_parameters": { "dimension": 1024, "input_type": "passage", "truncate": "END" }, "read_parameters": { "dimension": 1024, "input_type": "query", "truncate": "END" }, "vector_type": "dense" } }, { "name": "example-pod-index", "vector_type": "dense", "metric": "cosine", "dimension": 768, "status": { "ready": true, "state": "Ready" }, "host": "example-pod-index-bhnyigt.svc.us-east-1-aws.pinecone.io", "spec": { "pod": { "replicas": 1, "shards": 1, "pods": 1, "pod_type": "s1.x1", "environment": "us-east-1-aws" } }, "deletion_protection": "disabled", "tags": null } ] } ``` # Create a namespace Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/createnamespace https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml post /namespaces Create a namespace in a serverless index. For guidance and examples, see [Manage namespaces](https://docs.pinecone.io/guides/manage-data/manage-namespaces). **Note:** This operation is not supported for pod-based indexes. ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/namespaces" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" \ -d '{ "name": "example-namespace", "schema": { "fields": { "document_id": {"filterable": true}, "document_title": {"filterable": true}, "chunk_number": {"filterable": true}, "document_url": {"filterable": true}, "created_at": {"filterable": true} } } }' ``` ```json curl theme={null} { "name": "example-namespace", "record_count": "0", "schema": { "fields": { "document_title": { "filterable": true }, "document_url": { "filterable": true }, "chunk_number": { "filterable": true }, "document_id": { "filterable": true }, "created_at": { "filterable": true } } } } ``` # Delete a namespace Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/deletenamespace https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml delete /namespaces/{namespace} Delete a namespace from a serverless index. Deleting a namespace is irreversible; all data in the namespace is permanently deleted. For guidance and examples, see [Manage namespaces](https://docs.pinecone.io/guides/manage-data/manage-namespaces). **Note:** This operation is not supported for pod-based indexes. ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="YOUR_INDEX_HOST" NAMESPACE="YOUR_NAMESPACE" # To target the default namespace, use "__default__". curl -X DELETE "https://$INDEX_HOST/namespaces/$NAMESPACE" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" ``` # Get index stats Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/describeindexstats https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml post /describe_index_stats Return statistics about the contents of an index, including the vector count per namespace, the number of dimensions, and the index fullness. Serverless indexes scale automatically as needed, so index fullness is relevant only for pod-based indexes. Index fullness is also relevant for [dedicated read nodes](/guides/index-data/dedicated-read-nodes#index-fullness). The response includes `memoryFullness` and `storageFullness` alongside `indexFullness`, which summarizes overall capacity usage. For serverless on-demand indexes, all three values are typically `0` because storage and compute scale automatically. For dedicated indexes, monitor these values and [add shards](/guides/index-data/dedicated-read-nodes#add-or-remove-shards) before the index reaches capacity. ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="YOUR_INDEX_HOST" curl -X POST "https://$INDEX_HOST/describe_index_stats" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```jsonc curl theme={null} // EXAMPLE RESPONSE 1: Serverless index (on-demand) { "namespaces": { "example-namespace": { "vectorCount": 10000 } }, "indexFullness": 0, "totalVectorCount": 10000, "dimension": 1024, "metric": "cosine", "vectorType": "dense", "memoryFullness": 0, "storageFullness": 0 } // EXAMPLE RESPONSE 2: Serverless index (dedicated read nodes) { "namespaces": { "example-namespace": { "vectorCount": 705000 } }, "indexFullness": 0.01, "totalVectorCount": 705000, "dimension": 1536, "metric": "cosine", "vectorType": "dense", "memoryFullness": 0.01, "storageFullness": 0.01 } ``` # Describe a namespace Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/describenamespace https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml get /namespaces/{namespace} Describe a namespace in a serverless index, including the total number of vectors in the namespace. For guidance and examples, see [Manage namespaces](https://docs.pinecone.io/guides/manage-data/manage-namespaces). **Note:** This operation is not supported for pod-based indexes. ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="YOUR_INDEX_HOST" NAMESPACE="YOUR_NAMESPACE" # To target the default namespace, use "__default__". curl "https://$INDEX_HOST/namespaces/$NAMESPACE" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "name": "example-namespace", "record_count": 20000 } ``` # Fetch records Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/fetch https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml get /vectors/fetch Look up and return records by ID from a single namespace. The returned records include the vector data and/or metadata. For on-demand indexes, since vector values are retrieved from object storage, fetch operations may have increased latency. If you only need metadata or IDs, consider using the query operation with `includeValues` set to `false` instead. For guidance and examples, see [Fetch data](https://docs.pinecone.io/guides/manage-data/fetch-data). ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/vectors/fetch?ids=id-1&ids=id-2&namespace=example-namespace" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "vectors": { "id-1": { "id": "id-1", "values": [0.568879, 0.632687092, 0.856837332, ...] }, "id-2": { "id": "id-2", "values": [0.00891787093, 0.581895, 0.315718859, ...] } }, "namespace": "example-namespace", "usage": {"readUnits": 1}, } ``` # Fetch records by metadata Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/fetch_by_metadata https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml post /vectors/fetch_by_metadata Look up and return records by metadata from a single namespace. The returned records include the vector data and metadata. For guidance and examples, see [Fetch data](https://docs.pinecone.io/guides/manage-data/fetch-data). ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X POST "https://$INDEX_HOST/vectors/fetch_by_metadata" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" \ -d '{ "namespace": "__default__", "filter": {"genre": {"$eq": "Action/Adventure"}}, "limit": 2 }' ``` ```json curl theme={null} { "vectors": { "0": { "id": "0", "values": [ 0.0234527588, 0.0291595459 ... ], "metadata": { "box-office": 2923706026, "genre": "Action/Adventure", "summary": "On the alien world of Pandora, paraplegic Marine Jake Sully uses an avatar to walk again and becomes torn between his mission and protecting the planet's indigenous Na'vi people. The film stars Sam Worthington, Zoe Saldana, and Sigourney Weaver.", "title": "Avatar", "year": 2009 } }, "1": { "id": "1", "values": [ 0.0397644043, 0.013053894, ... ], "metadata": { "box-office": 2799439100, "genre": "Action/Adventure", "summary": "In the aftermath of Thanos wiping out half of the universe, the remaining Avengers assemble once more to undo the chaos, leading to a time-traveling adventure. Stars Robert Downey Jr., Chris Evans, and Scarlett Johansson.", "title": "Avengers: Endgame", "year": 2019 } } }, "namespace": "__default__", "usage": { "readUnits": 1 }, "pagination": { "next": "Tm90aGluZyB0byBzZWUgaGVyZQo=" } } ``` # List namespaces Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/listnamespaces https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml get /namespaces List all namespaces in a serverless index. Up to 100 namespaces are returned at a time by default, in sorted order (bitwise “C” collation). If the `limit` parameter is set, up to that number of namespaces are returned instead. Whenever there are additional namespaces to return, the response also includes a `pagination_token` that you can use to get the next batch of namespaces. When the response does not include a `pagination_token`, there are no more namespaces to return. For guidance and examples, see [Manage namespaces](https://docs.pinecone.io/guides/manage-data/manage-namespaces). **Note:** This operation is not supported for pod-based indexes. ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/namespaces" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "namespaces": [ { "name": "example-namespace", "record_count": 20000 }, { "name": "example-namespace2", "record_count": 10500 }, ... ], "pagination": { "next": "Tm90aGluZyB0byBzZWUgaGVyZQo=" } } ``` # Upsert records Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/upsert https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml post /vectors/upsert Upsert records into a namespace. If a new value is upserted for an existing record ID, it will overwrite the previous value. For guidance, examples, and limits, see [Upsert data](https://docs.pinecone.io/guides/index-data/upsert-data). To control costs when ingesting large datasets (10,000,000+ records), use [import](/guides/index-data/import-data) instead of upsert. ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/vectors/upsert" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2026-04" \ -d '{ "vectors": [ { "id": "vec1", "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1], "metadata": {"genre": "comedy", "year": 2020} }, { "id": "vec2", "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2], "metadata": {"genre": "documentary", "year": 2019} } ], "namespace": "example-namespace" }' ``` ``` ``` # Upsert text Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/upsert_records https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml post /records/namespaces/{namespace}/upsert Upsert text into a namespace. Pinecone converts the text to vectors automatically using the hosted embedding model associated with the index. Upserting text is supported only for [indexes with integrated embedding](https://docs.pinecone.io/guides/index-data/create-an-index#embedding-models). For guidance, examples, and limits, see [Upsert data](https://docs.pinecone.io/guides/index-data/upsert-data). ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index INDEX_HOST="INDEX_HOST" NAMESPACE="YOUR_NAMESPACE" PINECONE_API_KEY="YOUR_API_KEY" # Upsert records into a namespace # `chunk_text` fields are converted to dense vectors # `category` fields are stored as metadata curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/upsert" \ -H "Content-Type: application/x-ndjson" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" \ -d '{"_id": "rec1", "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.", "category": "digestive system"} {"_id": "rec2", "chunk_text": "Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today.", "category": "cultivation"} {"_id": "rec3", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.", "category": "immune system"} {"_id": "rec4", "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.", "category": "endocrine system"}' ``` # Describe a model Source: https://docs.pinecone.io/reference/api/2026-04/inference/describe_model https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/inference_2026-04.oas.yaml get /models/{model_name} Get a description of a model hosted by Pinecone. You can use hosted models as an integrated part of Pinecone operations or for standalone embedding and reranking. For more details, see [Vector embedding](https://docs.pinecone.io/guides/index-data/indexing-overview#vector-embedding) and [Rerank results](https://docs.pinecone.io/guides/search/rerank-results). ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl "https://api.pinecone.io/models/llama-text-embed-v2" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "model": "llama-text-embed-v2", "short_description": "A high performance dense embedding model optimized for multilingual and cross-lingual text question-answering retrieval with support for long documents (up to 2048 tokens) and dynamic embedding size (Matryoshka Embeddings).", "type": "embed", "vector_type": "dense", "default_dimension": 1024, "modality": "text", "max_sequence_length": 2048, "max_batch_size": 96, "provider_name": "NVIDIA", "supported_metrics": [ "Cosine", "DotProduct" ], "supported_dimensions": [ 384, 512, 768, 1024, 2048 ], "supported_parameters": [ { "parameter": "input_type", "required": true, "type": "one_of", "value_type": "string", "allowed_values": [ "query", "passage" ] }, { "parameter": "truncate", "required": false, "default": "END", "type": "one_of", "value_type": "string", "allowed_values": [ "END", "NONE", "START" ] }, { "parameter": "dimension", "required": false, "default": 1024, "type": "one_of", "value_type": "integer", "allowed_values": [ 384, 512, 768, 1024, 2048 ] } ] } ``` # Generate vectors Source: https://docs.pinecone.io/reference/api/2026-04/inference/generate-embeddings https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/inference_2026-04.oas.yaml post /embed Generate vector embeddings for input data. This endpoint uses Pinecone's [hosted embedding models](https://docs.pinecone.io/guides/index-data/create-an-index#embedding-models). ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl https://api.pinecone.io/embed \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" \ -d '{ "model": "llama-text-embed-v2", "parameters": { "input_type": "passage", "truncate": "END" }, "inputs": [ {"text": "Apple is a popular fruit known for its sweetness and crisp texture."}, {"text": "The tech company Apple is known for its innovative products like the iPhone."}, {"text": "Many people enjoy eating apples as a healthy snack."}, {"text": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."}, {"text": "An apple a day keeps the doctor away, as the saying goes."}, {"text": "Apple Computer Company was founded on April 1, 1976, by Steve Jobs, Steve Wozniak, and Ronald Wayne as a partnership."} ] }' ``` ```json curl theme={null} { "data": [ { "values": [ 0.04925537109375, -0.01313018798828125, -0.0112762451171875, ... ] }, ... ], "model": "llama-text-embed-v2", "usage": { "total_tokens": 130 } } ``` # List available models Source: https://docs.pinecone.io/reference/api/2026-04/inference/list_models https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/inference_2026-04.oas.yaml get /models List the embedding and reranking models hosted by Pinecone. You can use hosted models as an integrated part of Pinecone operations or for standalone embedding and reranking. For more details, see [Vector embedding](https://docs.pinecone.io/guides/index-data/indexing-overview#vector-embedding) and [Rerank results](https://docs.pinecone.io/guides/search/rerank-results). ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl "https://api.pinecone.io/models" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "models": [ { "model": "llama-text-embed-v2", "short_description": "A high performance dense embedding model optimized for multilingual and cross-lingual text question-answering retrieval with support for long documents (up to 2048 tokens) and dynamic embedding size (Matryoshka Embeddings).", "type": "embed", "vector_type": "dense", "default_dimension": 1024, "modality": "text", "max_sequence_length": 2048, "max_batch_size": 96, "provider_name": "NVIDIA", "supported_metrics": [ "Cosine", "DotProduct" ], "supported_dimensions": [ 384, 512, 768, 1024, 2048 ], "supported_parameters": [ { "parameter": "input_type", "required": true, "type": "one_of", "value_type": "string", "allowed_values": [ "query", "passage" ] }, { "parameter": "truncate", "required": false, "default": "END", "type": "one_of", "value_type": "string", "allowed_values": [ "END", "NONE", "START" ] }, { "parameter": "dimension", "required": false, "default": 1024, "type": "one_of", "value_type": "integer", "allowed_values": [ 384, 512, 768, 1024, 2048 ] } ] }, { "model": "multilingual-e5-large", "short_description": "A high-performance dense embedding model trained on a mixture of multilingual datasets. It works well on messy data and short queries expected to return medium-length passages of text (1-2 paragraphs)", "type": "embed", "vector_type": "dense", "default_dimension": 1024, "modality": "text", "max_sequence_length": 507, "max_batch_size": 96, "provider_name": "Microsoft", "supported_metrics": [ "Cosine", "Euclidean" ], "supported_dimensions": [ 1024 ], "supported_parameters": [ { "parameter": "input_type", "required": true, "type": "one_of", "value_type": "string", "allowed_values": [ "query", "passage" ] }, { "parameter": "truncate", "required": false, "default": "END", "type": "one_of", "value_type": "string", "allowed_values": [ "END", "NONE" ] } ] }, { "model": "pinecone-sparse-english-v0", "short_description": "A sparse embedding model for converting text to sparse vectors for keyword or hybrid semantic/keyword search. Built on the innovations of the DeepImpact architecture.", "type": "embed", "vector_type": "sparse", "modality": "text", "max_sequence_length": 512, "max_batch_size": 96, "provider_name": "Pinecone", "supported_metrics": [ "DotProduct" ], "supported_parameters": [ { "parameter": "input_type", "required": true, "type": "one_of", "value_type": "string", "allowed_values": [ "query", "passage" ] }, { "parameter": "truncate", "required": false, "default": "END", "type": "one_of", "value_type": "string", "allowed_values": [ "END", "NONE" ] }, { "parameter": "return_tokens", "required": false, "default": false, "type": "any", "value_type": "boolean" } ] }, { "model": "bge-reranker-v2-m3", "short_description": "A high-performance, multilingual reranking model that works well on messy data and short queries expected to return medium-length passages of text (1-2 paragraphs)", "type": "rerank", "modality": "text", "max_sequence_length": 1024, "max_batch_size": 100, "provider_name": "BAAI", "supported_parameters": [ { "parameter": "truncate", "required": false, "default": "NONE", "type": "one_of", "value_type": "string", "allowed_values": [ "END", "NONE" ] } ] }, { "model": "cohere-rerank-3.5", "short_description": "Cohere's leading reranking model, balancing performance and latency for a wide range of enterprise search applications.", "type": "rerank", "modality": "text", "max_sequence_length": 40000, "max_batch_size": 200, "provider_name": "Cohere", "supported_parameters": [ { "parameter": "max_chunks_per_doc", "required": false, "default": 3072, "type": "numeric_range", "value_type": "integer", "min": 1, "max": 3072 } ] }, { "model": "pinecone-rerank-v0", "short_description": "A state of the art reranking model that out-performs competitors on widely accepted benchmarks. It can handle chunks up to 512 tokens (1-2 paragraphs)", "type": "rerank", "modality": "text", "max_sequence_length": 512, "max_batch_size": 100, "provider_name": "Pinecone", "supported_parameters": [ { "parameter": "truncate", "required": false, "default": "END", "type": "one_of", "value_type": "string", "allowed_values": [ "END", "NONE" ] } ] } ] } ``` # Rerank results Source: https://docs.pinecone.io/reference/api/2026-04/inference/rerank https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/inference_2026-04.oas.yaml post /rerank Rerank results according to their relevance to a query. For guidance and examples, see [Rerank results](https://docs.pinecone.io/guides/search/rerank-results). ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl https://api.pinecone.io/rerank \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Api-Key: $PINECONE_API_KEY" \ -d '{ "model": "bge-reranker-v2-m3", "query": "The tech company Apple is known for its innovative products like the iPhone.", "return_documents": true, "top_n": 4, "documents": [ {"id": "vec1", "text": "Apple is a popular fruit known for its sweetness and crisp texture."}, {"id": "vec2", "text": "Many people enjoy eating apples as a healthy snack."}, {"id": "vec3", "text": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."}, {"id": "vec4", "text": "An apple a day keeps the doctor away, as the saying goes."} ], "parameters": { "truncate": "END" } }' ``` ```JSON curl theme={null} { "data":[ { "index":2, "document":{ "id":"vec3", "text":"Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces." }, "score":0.47654688 }, { "index":0, "document":{ "id":"vec1", "text":"Apple is a popular fruit known for its sweetness and crisp texture." }, "score":0.047963805 }, { "index":3, "document":{ "id":"vec4", "text":"An apple a day keeps the doctor away, as the saying goes." }, "score":0.007587992 }, { "index":1, "document":{ "id":"vec2", "text":"Many people enjoy eating apples as a healthy snack." }, "score":0.0006491712 } ], "usage":{ "rerank_units":1 } } ``` # Authentication Source: https://docs.pinecone.io/reference/api/authentication Pinecone API authentication guide covering API key generation, SDK client setup, and HTTP header configuration for authorized requests. All requests to [Pinecone APIs](/reference/api/introduction) must contain a valid [API key](/guides/production/security-overview#api-keys) for the target project. ## Get an API key [Create a new API key](https://app.pinecone.io/organizations/-/projects/-/keys) in the Pinecone console, or use the connect widget below to generate a key.
Copy your generated key: ``` PINECONE_API_KEY="{{YOUR_API_KEY}}" # This API key has ReadWrite access to all indexes in your project. ``` ## Initialize a client When using a [Pinecone SDK](/reference/pinecone-sdks), initialize a client object with your API key and then reuse the authenicated client in subsquent function calls. For example: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key='YOUR_API_KEY') # Creates an index using the API key stored in the client 'pc'. pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud='aws', region='us-east-1' ) ) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); // Creates an index using the API key stored in the client 'pc'. await pc.createIndex({ name: 'docs-example', dimension: 1536, metric: 'cosine', spec: { serverless: { cloud: 'aws', region: 'us-east-1' } } }) ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.IndexModel; import org.openapitools.db_control.client.model.DeletionProtection; public class CreateServerlessIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); // Creates an index using the API key stored in the client 'pc'. pc.createServerlessIndex("docs-example", "cosine", 1536, "aws", "us-east-1"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v3/pinecone" ) 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) } indexName := "docs-example" vectorType := "dense" dimension := int32(1536) metric := pinecone.Cosine deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: indexName, VectorType: &vectorType, Dimension: &dimension, Metric: &metric, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: &deletionProtection, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", err) } else { fmt.Printf("Successfully created serverless index: %v", idx.Name) } } ``` ```shell curl theme={null} curl -s "https://api.pinecone.io/indexes" \ -H "Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud":"aws", "region": "us-east-1" } } }' ``` ## Add headers to an HTTP request All HTTP requests to Pinecone APIs must contain an `Api-Key` header that specifies a valid [API key](/guides/production/security-overview#api-keys) and must be encoded as JSON with the `Content-Type: application/json` header. For example: ```shell curl theme={null} curl https://api.pinecone.io/indexes \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud":"aws", "region": "us-east-1" } } }' ``` ## Troubleshooting Older versions of Pinecone required you to initialize a client with an `init` method that takes both `api_key` and `environment` parameters, for example: ```python Python theme={null} # Legacy initialization import pinecone pc = pinecone.init( api_key="PINECONE_API_KEY", environment="PINECONE_ENVIRONMENT" ) ``` ```javascript JavaScript theme={null} // Legacy initialization import { Pinecone } from '@pinecone-database/pinecone'; const pineconeClient = new PineconeClient(); await pineconeClient.init({ apiKey: 'PINECONE_API_KEY', environment: 'PINECONE_ENVIRONMENT', }); ``` In more recent versions of Pinecone, this has changed. Initialization no longer requires an `init` step, and cloud environment is defined for each index rather than an entire project. Client initialization now only requires an `api_key` parameter, for example: ```python Python theme={null} # New initialization from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` ```javascript JavaScript theme={null} // New initialization import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); ``` If you are receiving errors about initialization, upgrade your [Pinecone SDK](/reference/pinecone-sdks) to the latest version, for example: ```shell Python theme={null} # Upgrade Pinecone SDK pip install pinecone --upgrade ``` ```shell JavaScript theme={null} # Upgrade Pinecone SDK npm install @pinecone-database/pinecone@latest ``` Also, note that some third-party tutorials and examples still reference the older initialization method. In such cases, follow the example above and the examples throughout the Pinecone documentation instead. # Pinecone Database limits Source: https://docs.pinecone.io/reference/api/database-limits Reference for Pinecone Database limits, covering upsert, query, fetch, delete, import, namespace, and rate limits for serverless indexes. This page describes different types of limits for Pinecone Database. **Looking for a specific limit?** * To compare monthly included usage by plan, start with [read units](#read-units-per-month-per-org), [write units](#write-units-per-month-per-org), and [model usage limits](#monthly-usage-limits). * If you received a `429` error, check [rate limits](#rate-limits), especially request-per-second limits for query, upsert, update, delete, fetch, and list. * For projects, users, indexes, namespaces, storage, backups, and collections, see [object limits](#object-limits). * For batch sizes, metadata filters, and identifier lengths, see [operation limits](#operation-limits) and [identifier limits](#identifier-limits). ## Rate limits Rate limits help protect your applications from misuse and maintain the health of our shared serverless infrastructure. These limits are designed to support typical production workloads while ensuring reliable performance for all users. **Most rate limits can be adjusted upon request.** If you need higher limits to scale your application, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. Pinecone is committed to supporting your growth and can often accommodate higher throughput requirements. Rate limits vary based on [pricing plan](https://www.pinecone.io/pricing/) and apply to [serverless indexes](/guides/index-data/indexing-overview) only. Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Data plane operations: request-per-second limits Pinecone enforces rate limits on the number of API requests per second at the namespace level for data plane operations (query, upsert, delete, and update). These limits provide protection against excessive request rates. #### Affected operations The following operations are subject to request-per-second rate limiting: | Operation | Scope | Limit | | --------- | ------------- | ----- | | Query | Per namespace | 100 | | Upsert | Per namespace | 100 | | Delete | Per namespace | 100 | | Update | Per namespace | 100 | #### Error response When you exceed the request-per-second limit, you'll receive an HTTP `429 - TOO_MANY_REQUESTS` response. The error message indicates which operation exceeded the limit and includes the namespace name and limit value. See the individual limit sections below for specific error message formats. #### How request-per-second limits work with limits on read and write units Request-per-second limits are enforced in addition to existing read unit and write unit limits. Requests must not exceed any applicable limits: * Index-level limits - read and write unit limits, per index * Namespace-level limits - read and write unit limits, per namespace * Request-per-second limits - requests per second, per namespace If any limit is exceeded, the request fails with a 429 error. #### Recommendations If you're hitting request-per-second limits: 1. Implement retry logic. Use exponential backoff to handle rate limit errors gracefully. See [Error Handling Guide](/guides/production/error-handling#implement-retry-logic). 2. Pace your requests. Add client-side rate limiting to stay under limits. 3. Consider [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes), which don't have request-per-second limits and provide dedicated capacity for high-throughput workloads. 4. If you need higher limits, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. ### All rate limits #### Monthly usage limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :---------------------------------------------------------------------------- | :------------- | :------------- | :------------- | :-------------- | | [Read units per month per org](#read-units-per-month-per-org) | 1,000,000 | 2,000,000 | Unlimited | Unlimited | | [Write units per month per org](#write-units-per-month-per-org) | 2,000,000 | 5,000,000 | Unlimited | Unlimited | | [Embedding tokens per month per model](#embedding-tokens-per-month-per-model) | 5,000,000 | 10,000,000 | Unlimited | Unlimited | | [Rerank requests per month per model](#rerank-requests-per-month-per-model) | Model-specific | Model-specific | Model-specific | Model-specific | #### Data operation throughput limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :------------------------------------------------------------------------------------------------------------ | :----------- | :----------- | :------------ | :-------------- | | [Upsert size per second per namespace](#upsert-size-per-second-per-namespace) | 50 MB | 50 MB | 50 MB | 50 MB | | [Query read units per second per index](#query-read-units-per-second-per-index) | 2,000 | 2,000 | 2,000 | 2,000 | | [Query requests per second per namespace](#query-requests-per-second-per-namespace) | 100 | 100 | 100 | 100 | | [Update records per second per namespace](#update-records-per-second-per-namespace) | 100 | 100 | 100 | 100 | | [Update requests per second per namespace](#update-requests-per-second-per-namespace) | 100 | 100 | 100 | 100 | | [Update by metadata requests per second per namespace](#update-by-metadata-requests-per-second-per-namespace) | 5 | 5 | 5 | 5 | | [Update by metadata requests per second per index](#update-by-metadata-requests-per-second-per-index) | 500 | 500 | 500 | 500 | | [Upsert requests per second per namespace](#upsert-requests-per-second-per-namespace) | 100 | 100 | 100 | 100 | | [Fetch requests per second per index](#fetch-requests-per-second-per-index) | 100 | 100 | 100 | 100 | | [List requests per second per index](#list-requests-per-second-per-index) | 200 | 200 | 200 | 200 | | [Describe index stats requests per second per index](#describe-index-stats-requests-per-second-per-index) | 100 | 100 | 100 | 100 | | [Delete requests per second per namespace](#delete-requests-per-second-per-namespace) | 100 | 100 | 100 | 100 | | [Delete records per second per namespace](#delete-records-per-second-per-namespace) | 5,000 | 5,000 | 5,000 | 5,000 | | [Delete records per second per index](#delete-records-per-second-per-index) | 5,000 | 5,000 | 5,000 | 5,000 | | [Delete by metadata requests per second per namespace](#delete-by-metadata-requests-per-second-per-namespace) | 5 | 5 | 5 | 5 | | [Delete by metadata requests per second per index](#delete-by-metadata-requests-per-second-per-index) | 500 | 500 | 500 | 500 | #### Model throughput limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :------------------------------------------------------------------------------ | :------------- | :------------- | :------------- | :-------------- | | [Embedding tokens per minute per model](#embedding-tokens-per-minute-per-model) | Model-specific | Model-specific | Model-specific | Model-specific | | [Rerank requests per minute per model](#rerank-requests-per-minute-per-model) | Model-specific | Model-specific | Model-specific | Model-specific | ### Read units per month per org | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 1,000,000 | 2,000,000 | Unlimited | Unlimited | [Read units](/guides/manage-cost/understanding-cost#read-units) measure the compute, I/O, and network resources used by [fetch](/guides/manage-data/fetch-data), [query](/guides/search/search-overview), and [list](/guides/manage-data/list-record-ids) requests to serverless indexes. When you reach the monthly read unit limit for an organization, fetch, query, and list requests to serverless indexes in the organization will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached your read unit limit for the current month limit. To continue reading data, upgrade your plan. ``` To continue reading from serverless indexes in the organization, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). To check how close you are to the monthly read unit limit for your organization, do the following: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select the project. 3. Select any index in the project. 4. Look under **Usage**. Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Write units per month per org | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 2,000,000 | 5,000,000 | Unlimited | Unlimited | [Write units](/guides/manage-cost/understanding-cost#write-units) measure the storage and compute resources used by [upsert](/guides/index-data/upsert-data), [update](/guides/manage-data/update-data), and [delete](/guides/manage-data/delete-data) requests to serverless indexes. When you reach the monthly write unit limit for an organization, upsert, update, and delete requests to serverless indexes in the organization will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached your write unit limit for the current month. To continue writing data, upgrade your plan. ``` To continue writing data to serverless indexes in the organization, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). To check how close you are to the monthly write unit limit for your organization, do the following: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select the project. 3. Select any index in the project. 4. Look under **Usage**. ### Upsert size per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 50 MB | 50 MB | 50 MB | 50 MB | When you reach the per second [upsert](/guides/index-data/upsert-data) size for a namespace in an index, additional upserts will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max upsert size limit per second for index . Pace your upserts or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Query read units per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 2,000 | 2,000 | 2,000 | 2,000 | Pinecone measures [query](/guides/search/search-overview) usage in [read units](/guides/manage-cost/understanding-cost#read-units). When you reach the per second limit for queries across all namespaces in an index, additional queries will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max query read units per second for index . Pace your queries or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). To check how many read units a query consumes, [check the query response](/guides/manage-cost/monitor-usage-and-costs#read-units). Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Query requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [query](/guides/search/search-overview) limit for a namespace in an index, additional queries will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the query QPS limit for namespace {namespace_name} ({limit} QPS). Pace your queries, consider Dedicated Read Nodes for your index, or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Update records per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [update](/guides/manage-data/update-data) limit for a namespace in an index, additional updates will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max update records per second for namespace . Pace your update requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Update requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [update](/guides/manage-data/update-data) request limit for a namespace in an index, additional update requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the update QPS limit for namespace {namespace_name} ({limit} QPS). Pace your update requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). If you need to update most of the records in a large namespace, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) for help creating an export to enable a faster and more cost-effective approach. ### Update by metadata requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5 | 5 | 5 | 5 | When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit for a namespace in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max update by metadata requests per second for namespace . Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Update by metadata requests per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 500 | 500 | 500 | 500 | When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit across all namespaces in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max update by metadata requests per second for index . Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Upsert requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [upsert](/guides/index-data/upsert-data) request limit for a namespace in an index, additional upsert requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the upsert QPS limit for namespace {namespace_name} ({limit} QPS). Pace your upsert requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Fetch requests per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [fetch](/guides/manage-data/fetch-data) limit across all namespaces in an index, additional fetch requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max fetch requests per second for index . Pace your fetch requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### List requests per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 200 | 200 | 200 | 200 | When you reach the per second [list](/guides/manage-data/list-record-ids) limit across all namespaces in an index, additional list requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max list requests per second for index . Pace your list requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Describe index stats requests per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [describe index stats](/reference/api/2024-10/data-plane/describeindexstats) limit across all namespaces in an index, additional describe index stats requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max describe_index_stats requests per second for index . Pace your describe_index_stats requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [delete](/guides/manage-data/delete-data) request limit for a namespace in an index, additional delete requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the delete QPS limit for namespace {namespace_name} ({limit} QPS). Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete records per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5000 | 5000 | 5000 | 5000 | When you reach the per second [delete](/guides/manage-data/delete-data) limit for a namespace in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete records per second for namespace . Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete records per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5000 | 5000 | 5000 | 5000 | When you reach the per second [delete](/guides/manage-data/delete-data) limit across all namespaces in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete records per second for index . Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete by metadata requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5 | 5 | 5 | 5 | When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit for a namespace in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete by metadata requests per second for namespace . Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete by metadata requests per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 500 | 500 | 500 | 500 | When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit across all namespaces in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete by metadata requests per second for index . Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Embedding tokens per minute per model | Embedding model | Input type | Starter plan | Builder plan | Standard plan | Enterprise plan | | :--------------------------- | :--------- | :----------- | :----------- | :------------ | :-------------- | | `llama-text-embed-v2` | Passage | 250,000 | 250,000 | 1,000,000 | 1,000,000 | | | Query | 50,000 | 50,000 | 250,000 | 250,000 | | `multilingual-e5-large` | Passage | 250,000 | 250,000 | 1,000,000 | 1,000,000 | | | Query | 50,000 | 50,000 | 250,000 | 250,000 | | `pinecone-sparse-english-v0` | Passage | 250,000 | 250,000 | 3,000,000 | 3,000,000 | | | Query | 250,000 | 250,000 | 3,000,000 | 3,000,000 | When you reach the per minute token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max embedding tokens per minute () model ''' and input type '' for the current project. To increase this limit, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). Otherwise, you can handle this limit by [implementing retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). ### Embedding tokens per month per model | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5,000,000 | 10,000,000 | Unlimited | Unlimited | When you reach the monthly token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the embedding token limit () for model for the current month. To continue using this model, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Rerank requests per minute per model | Reranking model | Starter plan | Builder plan | Standard plan | Enterprise plan | | :--------------------- | :------------ | :------------ | :------------ | :-------------- | | `cohere-rerank-4-fast` | Not available | Not available | 300 | 300 | | `cohere-rerank-3.5` | Not available | Not available | 300 | 300 | | `bge-reranker-v2-m3` | 60 | 60 | 60 | 60 | | `pinecone-rerank-v0` | 60 | Not available | 60 | 60 | When you reach the per minute request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max rerank requests per minute () for model '' for the current project. To increase this limit, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Rerank requests per month per model | Reranking model | Starter plan | Builder plan | Standard plan | Enterprise plan | | :--------------------- | :------------ | :------------ | :------------ | :-------------- | | `cohere-rerank-4-fast` | Not available | Not available | Unlimited | Unlimited | | `cohere-rerank-3.5` | Not available | Not available | Unlimited | Unlimited | | `bge-reranker-v2-m3` | 500 | 1,000 | Unlimited | Unlimited | | `pinecone-rerank-v0` | 500 | Not available | Unlimited | Unlimited | When you reach the monthly request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the rerank request limit () for model for the current month. To continue using this model, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Inference requests per second or minute, per project | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :---------------------------- | :----------- | :----------- | :------------ | :-------------- | | Inference requests per second | 100 | 100 | 100 | 100 | | Inference requests per minute | 2000 | 2000 | 2000 | 2000 | When you reach the per second or per minute request limit, inference requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max inference requests per second () for the current project. ``` This error indicates per second or per minute, as applicable. To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). ## Object limits Object limits are restrictions on the number or size of objects in Pinecone. Object limits vary based on [pricing plan](https://www.pinecone.io/pricing/). | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :----------------------------------------------------------------------------- | :----------- | :----------- | :------------ | :-------------- | | [Projects per organization](#projects-per-organization) | 1 | 5 | 20 | 100 | | [Users per organization](#users-per-organization) | 2 | 5 | Unlimited | Unlimited | | [Serverless indexes per project](#serverless-indexes-per-project) 1 | 5 | 10 | 20 | 200 | | [Serverless index storage per org](#serverless-index-storage-per-org) | 2 GB | 10 GB | N/A | N/A | | [Namespaces per serverless index](#namespaces-per-serverless-index) | 100 | 1,000 | 100,000 | 100,000 | | [Serverless backups per project](#serverless-backups-per-project) | N/A | N/A | 500 | 1000 | | [Collections per project](#collections-per-project) | 100 | N/A | N/A | N/A | 1 On the Starter plan, all serverless indexes must be in the `us-east-1` region of AWS. Builder, Standard, and Enterprise plans can create indexes in any [supported region](/guides/index-data/create-an-index#cloud-regions).
### Projects per organization | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 1 | 5 | 20 | 100 | When you reach this quota for an organization, trying to [create projects](/guides/projects/create-a-project) will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max projects allowed in organization . To add more projects, upgrade your plan. ``` To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Users per organization | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 2 | 5 | Unlimited | Unlimited | When you reach this quota for an organization, trying to add users to the organization will fail. To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Serverless indexes per project | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5 | 10 | 20 | 200 | When you reach this quota for a project, trying to [create serverless indexes](/guides/index-data/create-an-index#create-a-serverless-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max serverless indexes allowed in project . Use namespaces to partition your data into logical groups, or upgrade your plan to add more serverless indexes. ``` To stay under this quota, consider using [namespaces](/guides/index-data/create-an-index#namespaces) instead of creating multiple indexes. Namespaces let you partition your data into logical groups within a single index. This approach not only helps you stay within index limits, but can also improve query performance and lower costs by limiting searches to relevant data subsets. To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Serverless index storage per org This limit applies to organizations on the Starter and Builder plans only. | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 2 GB | 10 GB | N/A | N/A | When you've reached this quota for an organization, updates and upserts into serverless indexes will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max storage allowed for organization . To update or upsert new data, delete records or upgrade your plan. ``` To continue writing data into your serverless indexes, [delete records](/guides/manage-data/delete-data) to bring your organization under the limit or [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Namespaces per serverless index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 1,000 | 100,000 | 100,000 | When you reach this quota for a serverless index, trying to [upsert records into a new namespace](/guides/index-data/upsert-data) in the index will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max namespaces allowed in serverless index . To add more namespaces, upgrade your plan. ``` To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). [Namespaces per serverless index](/reference/api/database-limits#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](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Serverless backups per project | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | N/A | N/A | 500 | 1000 | Backups are not available on the Starter or Builder plans. On the Standard and Enterprise plans, when you reach this quota for a project, trying to [create serverless backups](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Backup failed to create. Quota for number of backups per index exceeded. ``` ### Collections per project | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | N/A | N/A | N/A | When you reach this quota for a project, trying to [create collections](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max collections allowed in project . To add more collections, upgrade your plan. ``` To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ## Operation limits Operation limits are restrictions on the size, number, or other characteristics of operations in Pinecone. Operation limits are fixed and do not vary based on pricing plan. ### Upsert limits | Metric | Limit | | :----------------------------------------------------------------- | :------------------------------------------------------------ | | Max [batch size](/guides/index-data/upsert-data#upsert-in-batches) | 2 MB or 1000 records with vectors
96 records with text | | Max documents per upsert request | 1000 | | Max document upsert request size | 2 MB | | Max document size | 2 MB | | Max `full_text_search` string fields per schema | 100 | | Max size per `full_text_search` string field | 100 KB | | Max tokens per `full_text_search` string field | 10,000 | | Max bytes per token | 256 bytes | | Max filterable metadata size per document | 40 KB | | Max length for a record ID | 512 characters | | Max dimensionality for dense vectors | 20,000 | | Max non-zero values for sparse vectors | 2048 | | Max dimensionality for sparse vectors | 4.2 billion | The 40 KB filterable metadata limit does not apply to `full_text_search` text fields. ### Import limits If your import exceeds these limits, you'll get an error specifying the limit exceeded. See [Troubleshooting](/guides/index-data/import-data#troubleshooting) for details. | Metric | Limit | | :-------------------------------------------- | :-------- | | Max namespaces per import | 10,000 | | Max total input data size (on-demand indexes) | 1 TB | | Max total input data size (DRN indexes) | Unlimited | | Max files per import | 100,000 | | Max size per file | 10 GB | The total input data size limit does not apply to indexes with [dedicated read nodes](/guides/index-data/dedicated-read-nodes). Bulk import supports indexes without a schema definition (Parquet files) and indexes with document schemas ([JSONL files](/guides/search/full-text-search#bulk-import)). Semantic-text (auto-embedded) fields are not yet supported in document schemas. ### Query limits | Metric | Limit | | :---------------- | :----- | | Max `top_k` value | 10,000 | | Max result size | 4MB | The query result size is affected by the dimension of the dense vectors and whether or not dense vector values and metadata are included in the result. If a query fails due to exceeding the 4MB result size limit, choose a lower `top_k` value, or use `include_metadata=False` or `include_values=False` to exclude metadata or values from the result. For better performance, especially with higher `top_k` values, avoid including vector values unless you need them. ### Fetch limits **Fetch by ID limits:** | Metric | Limit | | :------------------------------- | :---- | | Max record IDs per fetch request | 1,000 | **Fetch by metadata limits:** | Metric | Limit | | :----------------------- | :---------------------------------- | | Max records per response | 10,000 | | Max response size | 4 MB | | Max request rate | 5 requests per second per namespace | To retrieve more than 10,000 matching records, paginate through results using the `paginationToken` parameter. See [Fetch records by metadata](/guides/manage-data/fetch-data#fetch-records-by-metadata). ### Delete limits | Metric | Limit | | :-------------------------------- | :---- | | Max record IDs per delete request | 1,000 | ### Metadata filter limits The following limits apply to [metadata filter expressions](/guides/search/filter-by-metadata#metadata-filter-expressions) used in query, delete, update, and fetch operations. | Limit | Value | Description | | :------------------------------------------ | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Maximum values per `$in` or `$nin` operator | 10,000 | Each `$in` or `$nin` operator accepts up to 10,000 values in its array. This limit applies per operator—if you have multiple `$in` operators in a single filter, each is independently limited to 10,000 values. | When you exceed this limit, the request will fail and return a `400 - BAD_REQUEST` error. #### Rationale Large `$in` operators can impact query performance and cost. Filters with thousands of values increase request payload size and end-to-end latency. Additionally, using large filters typically indicates a shared namespace architecture, which increases query costs—queries scan the entire namespace regardless of filters. #### Alternative approaches If you need to filter by more than 10,000 values, consider these alternatives: * **Use namespaces for tenant isolation**: Instead of filtering by tenant IDs within a single namespace, create separate namespaces for each tenant or tenant group. This can also reduce query costs. See [Design for multi-tenancy](/guides/index-data/data-modeling#design-for-multi-tenancy). * **Use broader access control groups**: Instead of filtering by individual user IDs, filter by organization, project, or role. This reduces the number of values in your `$in` filter. See [Design for multi-tenancy](/guides/index-data/data-modeling#use-access-control-groups-instead-of-individual-ids). * **Post-filter client-side**: Retrieve a larger top K without filtering (for example, top 1000), then filter results client-side. * **Run multiple queries**: Split your filter into multiple queries with smaller `$in` operators and combine the results client-side. To avoid hitting this limit in production, validate the size of your `$in` and `$nin` arrays in your application code before making the request to Pinecone. ## Identifier limits An identifier is a string of characters used to identify "named" [objects in Pinecone](/guides/get-started/concepts). The following Pinecone objects use strings as identifiers: | Object | Field | Max # characters | Allowed characters | | --------------------------------------------------------- | ----------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | [Organization](/guides/get-started/concepts#organization) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Project](/guides/get-started/concepts#project) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Index](/guides/get-started/concepts#index) | `name` | 45 |
  • `a-z`, `0-9`, and `-`
  • Must be lowercase
  • Cannot start or end with `-`
  • Cannot be empty
| | [Namespace](/guides/get-started/concepts#namespace) | `namespace` | 512 |
  • ASCII except `\0`
  • For the default namespace, use `""` (or `"__default__"`, in API versions `2025-04` and later)
| | [Record](/guides/get-started/concepts#record) | `id` | 512 |
  • ASCII except `\0`
  • Cannot be empty
| # Errors Source: https://docs.pinecone.io/reference/api/errors Pinecone REST API: Pinecone uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the range. Pinecone uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that failed given the information provided, and codes in the `5xx` range indicate an error with Pinecone's servers. For guidance on handling errors in production, see [Error handling](/guides/production/error-handling). ## 200 - OK The request succeeded. ## 201 - CREATED The request succeeded and a new resource was created. ## 202 - NO CONTENT The request succeeded, but there is no content to return. ## 400 - INVALID ARGUMENT The request failed due to an invalid argument. ## 401 - UNAUTHENTICATED The request failed due to a missing or invalid [API key](/guides/projects/understanding-projects#api-keys). ## 402 - PAYMENT REQUIRED The request failed due to delinquent payment or account deactivation for non-payment. See [Account deactivation for non-payment](/guides/organizations/manage-billing/non-payment-account-deactivation). ## 403 - FORBIDDEN The request failed due to an exceeded [quota](/reference/api/database-limits#object-limits) or [index deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection). ## 404 - NOT FOUND The request failed because the resource was not found. ## 409 - ALREADY EXISTS The request failed because the resource already exists. ## 412 - FAILED PRECONDITIONS The request failed due to preconditions not being met. | ## 422 - UNPROCESSABLE ENTITY The request failed because the server was unable to process the contained instructions. ## 429 - TOO MANY REQUESTS The request was [rate-limited](/reference/api/database-limits#rate-limits). [Implement retry logic with exponential backoff](/guides/production/error-handling#handle-rate-limits-429) to handle this error. ## 500 - UNKNOWN An internal server error occurred. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. ## 502 - BAD GATEWAY The API gateway received an invalid response from a backend service. This is typically a temporary error. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. ## 503 - UNAVAILABLE The server is currently unavailable. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. ## 504 - GATEWAY TIMEOUT The API gateway did not receive a timely response from the backend server. This can occur due to slow requests or backend processing delays. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. # API reference Source: https://docs.pinecone.io/reference/api/introduction Pinecone API reference overview for Database, Inference, and Admin endpoints with supported SDKs including Python, Node.js, Java, and Go. Pinecone's APIs let you interact programmatically with your Pinecone account. [SDK versions](/reference/pinecone-sdks#sdk-versions) are pinned to specific API versions. ## Database Use the Database API to store and query records in [Pinecone Database](/guides/get-started/quickstart). The following Pinecone SDKs support the Database API: ## Inference Use the Inference API to generate vector embeddings and rerank results using [embedding models](/guides/index-data/create-an-index#embedding-models) and [reranking models](/guides/search/rerank-results#reranking-models) hosted on Pinecone's infrastructure. There are two ways to use the Inference API: * As a standalone service, through the [Rerank documents](/reference/api/latest/inference/rerank) and [Generate vectors](/reference/api/latest/inference/generate-embeddings) endpoints. * As an integrated part of database operations, through the [Create an index with integrated embedding](/reference/api/latest/control-plane/create_for_model), [Upsert text](/reference/api/latest/data-plane/upsert_records), and [Search with text](/reference/api/latest/data-plane/search_records) endpoints. The following Pinecone SDKs support using the Inference API: # Known limitations Source: https://docs.pinecone.io/reference/api/known-limitations Known limitations and feature restrictions for Pinecone indexes, including upsert consistency, metadata rules, and serverless caveats. This page describes known limitations and feature restrictions in Pinecone. ## General * [Upserts](/guides/index-data/upsert-data) * Pinecone is eventually consistent, so there can be a slight delay before upserted records are available to query. After upserting records, use the [`describe_index_stats`](/reference/api/2024-10/data-plane/describeindexstats) operation to check if the current vector count matches the number of records you expect, although this method may not work for pod-based indexes with multiple replicas. * Only indexes using the [dotproduct distance metric](/guides/index-data/indexing-overview#dotproduct) support querying sparse-dense vectors. Upserting, updating, and fetching sparse-dense vectors in indexes with a different distance metric will succeed, but querying will return an error. * Indexes created before February 22, 2023 do not support sparse vectors. * [Metadata](/guides/index-data/upsert-data#upsert-with-metadata-filters) * Null metadata values aren't supported. Instead of setting a key to `null`, remove the key from the metadata payload. * Nested JSON objects are not supported. ## Serverless indexes Serverless indexes do not support the following features: * [Filtering index statistics by metadata](/reference/api/2024-10/data-plane/describeindexstats) * [Private endpoints](/guides/production/configure-private-endpoints) * This feature is available on AWS only. # API versioning Source: https://docs.pinecone.io/reference/api/versioning Pinecone REST API: Pinecone's APIs are versioned to ensure that your applications continue to work as expected as the platform evolves. Pinecone's APIs are versioned to ensure that your applications continue to work as expected as the platform evolves. Versions are named by release date in the format `YYYY-MM`, for example, `2025-10`. ## Release schedule On a quarterly basis, Pinecone releases a new **stable** API version as well as a **release candidate** of the next stable version. * **Stable:** Each stable version remains unchanged and supported for a minimum of 12 months. Since stable versions are released every 3 months, this means you have at least 9 months to test and migrate your app to the newest stable version before support for the previous version is removed. * **Release candidate:** The release candidate gives you insight into the upcoming changes in the next stable version. It is available for approximately 3 months before the release of the stable version and can include new features, improvements, and [breaking changes](#breaking-changes). Below is an example of Pinecone's release schedule: ## Specify an API version When using the API directly, it is important to specify an API version in your requests. If you don't, requests default to the oldest supported stable version. Once support for that version ends, your requests will default to the next oldest stable version, which could include breaking changes that require you to update your integration. To specify an API version, set the `X-Pinecone-Api-Version` header to the version name. For example, to use the latest stable version (`2026-04`) to describe an index, set the `X-Pinecone-Api-Version` header: ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/indexes/movie-recommendations" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" ``` To use an older version, specify that version instead. ## SDK versions Official [Pinecone SDKs](/reference/pinecone-sdks) provide convenient access to Pinecone APIs. SDK versions are pinned to specific API versions. When a new API version is released, a new version of the SDK is also released. For the mapping between SDK and API versions, see [SDK versions](/reference/pinecone-sdks#sdk-versions). ## Breaking changes Breaking changes are changes that can potentially break your integration with a Pinecone API. Breaking changes include: * Removing an entire operation * Removing or renaming a parameter * Removing or renaming a response field * Adding a new required parameter * Making a previously optional parameter required * Changing the type of a parameter or response field * Removing enum values * Adding a new validation rule to an existing parameter * Changing authentication or authorization requirements ## Non-breaking changes Non-breaking changes are additive and should not break your integration. Additive changes include: * Adding an operation * Adding an optional parameter * Adding an optional request header * Adding a response field * Adding a response header * Adding enum values ## Get updates To ensure you always know about upcoming API changes, follow the [Release notes](/release-notes/). # CLI authentication Source: https://docs.pinecone.io/reference/cli/authentication Authenticate the Pinecone CLI using user login, service accounts, or API keys, including auth priority and Admin API access rules. This document describes how to authenticate the Pinecone CLI to manage your Pinecone resources. ## Authentication methods | Method | Admin API | Control/data plane | Best for | | ----------------------------------- | --------- | ------------------ | -------------------------------- | | [User login](#user-login) | ✅ | ✅ | Interactive use | | [Service account](#service-account) | ✅ | ✅ | Automation with Admin API access | | [API key](#api-key) | ❌ | ✅ | Simple automation, CI/CD | ### User login Authenticate through a web browser. The token refreshes automatically and stays valid for up to 120 days (re-auth required after 30 days of inactivity). ```bash theme={null} pc auth login ``` The CLI auto-targets your default organization and its first project. Change with `pc target -o "my-org" -p "my-project"`. ### Service account Authenticate with credentials from a [service account](/guides/organizations/manage-service-accounts). ```bash theme={null} pc auth configure --client-id "ID" --client-secret "SECRET" # Or via environment variables export PINECONE_CLIENT_ID="your-client-id" export PINECONE_CLIENT_SECRET="your-client-secret" ``` The CLI auto-targets the service account's organization. For projects: auto-selects if one exists, prompts if multiple exist, or set manually with `pc target -p "my-project"`. ### API key Authenticate with an [API key](/guides/projects/manage-api-keys). API keys can't access the Admin API. ```bash theme={null} pc auth configure --api-key "YOUR_API_KEY" # Or via environment variable export PINECONE_API_KEY="your-api-key" ``` API keys are scoped to a specific project. When set, control/data plane operations use the **key's project**, ignoring any [target context](/reference/cli/target-context) you've set. ## Auth priority When multiple credentials exist, the CLI chooses based on operation type. Within each credential type, environment variables take precedence over stored configuration. **Control/data plane operations:** 1. API key 2. User login token (via [managed keys](#managed-keys)) 3. Service account (via [managed keys](#managed-keys)) **Admin API operations:** 1. User login token 2. Service account User login and service account are mutually exclusive when configured via CLI commands—each clears the other. However, service account env vars don't clear a stored user login token. **Example scenarios:** * If `PINECONE_API_KEY` is set, the CLI uses it for control/data plane operations, regardless of any stored API key. * If you're logged in via `pc auth login` and also have `PINECONE_CLIENT_ID`/`PINECONE_CLIENT_SECRET` set, the user login token is used for everything—the service account env vars are ignored. * If you have an API key configured and are also logged in, the API key is used for control/data plane operations, but user login is used for Admin API operations (since API keys can't access Admin API). ## Managed keys When using user login or service account (without a default API key), the CLI automatically creates and manages API keys for control/data plane operations. This happens transparently on first use. * **Stored locally:** `~/.config/pinecone/secrets.yaml` (permissions 0600) * **Stored remotely:** Visible in console as `pinecone-cli-{id}` with origin `cli_created` ```bash theme={null} # List locally tracked managed keys pc auth local-keys list # Delete managed keys (local + remote) pc auth local-keys prune # Delete only CLI-created managed keys pc auth local-keys prune --origin cli # Delete only user-created managed keys pc auth local-keys prune --origin user # Delete a specific API key by ID pc api-key delete --id "KEY_ID" ``` When you run `pc api-key create --store` for a project that already has a CLI-created managed key, the CLI automatically deletes the old remote key before storing the new one. ## Logging out ```bash theme={null} pc auth logout ``` Clears all local auth data: tokens, credentials, API keys, managed keys, and [target context](/reference/cli/target-context). `pc auth logout` doesn't delete managed keys from Pinecone's servers. Run `pc auth local-keys prune` first for full cleanup. ## Local storage Auth data is stored in `~/.config/pinecone/` with 0600 permissions: | File | Contents | | -------------- | ---------------------------------------------------------------- | | `secrets.yaml` | OAuth token, service account credentials, API keys, managed keys | | `state.yaml` | Target org/project | | `config.yaml` | CLI settings (color, environment) | ## Check status ```bash theme={null} pc auth status ``` Shows your current authentication method, target organization and project, token expiration (for user login), and environment configuration. # CLI command reference Source: https://docs.pinecone.io/reference/cli/command-reference Complete Pinecone CLI command reference covering syntax, subcommands, flags, help output, and exit codes for auth, index, and project. This document provides a complete reference for all Pinecone CLI commands. ## Command structure The Pinecone CLI uses a hierarchical command structure. Each command consists of a primary command followed by one or more subcommands and optional flags. ```bash theme={null} pc [flags] pc [flags] ``` For example: ```bash theme={null} # Top-level command with flags pc target -o "organization-name" -p "project-name" # Command (index) and subcommand (list) pc index list # Command (index) and subcommand (create) with flags pc index create \ --name my-index \ --dimension 1536 \ --metric cosine \ --cloud aws \ --region us-east-1 # Command (auth) and nested subcommands (local-keys prune) with flags pc auth local-keys prune --id proj-abc123 --skip-confirmation ``` ## Getting help The CLI provides help for commands at every level: ```bash theme={null} # top-level help pc --help pc -h # command help pc auth --help pc index --help pc project --help # subcommmand help pc index create --help pc project create --help pc auth configure --help # nested subcommand help pc auth local-keys prune --help ``` ## Exit codes All commands return exit code `0` for success and `1` for error. ## Available commands This section describes all commands offered by the Pinecone CLI. ### Top-level commands **Description** Authenticate via a web browser. After login, set a [target org and project](/reference/cli/target-context) with `pc target` before accessing data. This command defaults to an initial organization and project to which you have access (these values display in the terminal), but you can change them with `pc target`. **Usage** ```bash theme={null} pc login ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Log in via browser pc login # Then set target context pc target -o "my-org" -p "my-project" ``` This is an alias for `pc auth login`. Both commands perform the same operation. **Description** Clears all authentication data from local storage, including: * User login token * Service account credentials (client ID and secret) * Default (manually specified) API key * Locally managed keys (for all projects) * Target organization and project context **Usage** ```bash theme={null} pc logout ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Clear all credentials and context pc logout ``` This is an alias for `pc auth logout`. Both commands perform the same operation. Does not delete managed API keys from Pinecone's servers. Run `pc auth local-keys prune` before logging out to fully clean up. **Description** Set the target organization and project for the CLI. Supports interactive organization and project selection or direct specification via flags. For details, see [CLI target context](/reference/cli/target-context). **Usage** ```bash theme={null} pc target [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------ | :--------- | :----------------------------- | | `--clear` | | Clear target context | | `--json` | `-j` | Output in JSON format | | `--org` | `-o` | Organization name | | `--organization-id` | | Organization ID | | `--project` | `-p` | Project name | | `--project-id` | | Project ID | | `--show` | `-s` | Display current target context | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Interactive targeting after login pc login pc target # Set specific organization and project pc target -o "my-org" -p "my-project" # Show current context pc target --show # Clear all context pc target --clear ``` **Description** Displays version information for the CLI, including the version number, commit SHA, and build date. **Usage** ```bash theme={null} pc version ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Display version information pc version ``` **Description** Displays information about the currently authenticated user. To use this command, you must be authenticated via user login. **Usage** ```bash theme={null} pc whoami ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc whoami ``` This is an alias for `pc auth whoami`. Both commands perform the same operation. ### Authentication **Description** Selectively clears specific authentication data without affecting other credentials. At least one flag is required. **Usage** ```bash theme={null} pc auth clear [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------ | :--------- | :-------------------------------------------------- | | `--api-key` | | Clear only the default (manually specified) API key | | `--service-account` | | Clear only service account credentials | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Clear only the default (manually specified) API key pc auth clear --api-key pc auth status # Clear service account pc auth clear --service-account ``` More surgical than `pc auth logout`. Does not clear user login token or managed keys. For those, use `pc auth logout` or `pc auth local-keys prune`. **Description** Configures service account credentials or a default (manually specified) API key. Service accounts automatically target the organization and prompt for project selection, unless there is only one project. A default API key overrides any previously specified target organization/project context. When setting a service account, this operation clears the user login token, if one exists. For details, see [CLI target context](/reference/cli/target-context). **Usage** ```bash theme={null} pc auth configure [flags] ``` **Flags** | Long flag | Short flag | Description | | :---------------------- | :--------- | :--------------------------------------------------- | | `--api-key` | | Default API key to use for authentication | | `--client-id` | | Service account client ID | | `--client-secret` | | Service account client secret | | `--client-secret-stdin` | | Read client secret from stdin | | `--json` | `-j` | Output in JSON format | | `--project-id` | `-p` | Target project ID (optional, interactive if omitted) | | `--prompt-if-missing` | | Prompt for missing credentials | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Service account setup (auto-targets org and prompts for project) pc auth configure --client-id my-id --client-secret my-secret # Service account with specific project pc auth configure \ --client-id my-id \ --client-secret my-secret \ -p proj-123 # Default API key (overrides any target context) pc auth configure --api-key pcsk_abc123 ``` `pc auth configure --api-key "YOUR_API_KEY"` does the same thing as `pc config set-api-key "YOUR_API_KEY"`. To learn about targeting a project after authenticating with a service account, see [CLI target context](/reference/cli/target-context). **Description** Displays all [managed API keys](/reference/cli/authentication#managed-keys) stored locally by the CLI, with various details. **Usage** ```bash theme={null} pc auth local-keys list [flags] ``` **Flags** | Long flag | Short flag | Description | | :--------- | :--------- | :----------------------------------------- | | `--json` | `-j` | Output in JSON format | | `--reveal` | | Show the actual API key values (sensitive) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all locally managed keys pc auth local-keys list # Show key values pc auth local-keys list --reveal # After storing a key pc api-key create -n "my-key" --store pc auth local-keys list ``` **Description** Deletes locally stored [managed API keys](/reference/cli/authentication#managed-keys) from local storage and Pinecone's servers. Filters by origin (`cli`/`user`/`all`) or project ID. **Usage** ```bash theme={null} pc auth local-keys prune [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :---------------------------------------------------------- | | `--dry-run` | | Preview deletions without applying | | `--id` | | Prune keys for specific project ID only | | `--json` | `-j` | Output in JSON format | | `--origin` | `-o` | Filter by origin - `cli`, `user`, or `all` (default: `all`) | | `--skip-confirmation` | | Skip confirmation prompt | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Preview deletions pc auth local-keys prune --dry-run # Delete CLI-created keys only pc auth local-keys prune -o cli --skip-confirmation # Delete for specific project pc auth local-keys prune --id proj-abc123 # Before/after check pc auth local-keys list pc auth local-keys prune -o cli pc auth local-keys list ``` This deletes keys from both local storage and Pinecone servers. Use `--dry-run` to preview before committing. **Description** Authenticate via user login in the web browser. After login, [set a target org and project](/reference/cli/target-context). **Usage** ```bash theme={null} pc auth login pc login # shorthand ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Login and set target pc auth login pc target -o "my-org" -p "my-project" pc index list ``` Tokens refresh automatically and remain valid for up to 120 days. If you're inactive for more than 30 days, you must re-authenticate. Logging in clears any existing service account credentials. This command does the same thing as `pc login`. **Description** Clears all authentication data from local storage, including: * User login token * Service account credentials (client ID and secret) * Default (manually specified) API key * Locally managed keys (for all projects) * Target organization and project context **Usage** ```bash theme={null} pc auth logout ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Clear all credentials and context pc auth logout ``` This command does the same thing as `pc logout`. Does not delete managed API keys from Pinecone's servers. Run `pc auth local-keys prune` before logging out to fully clean up. **Description** Shows details about all configured authentication methods. **Usage** ```bash theme={null} pc auth status [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Check status after login pc auth login pc auth status # JSON output for scripting pc auth status --json ``` **Description** Displays information about the currently authenticated user. To use this command, you must be authenticated via user login. **Usage** ```bash theme={null} pc auth whoami ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc auth whoami ``` This command does the same thing as `pc whoami`. ### Indexes **Description** Modifies the configuration of an existing index. **Usage** ```bash theme={null} pc index configure [flags] ``` **Flags** | Long flag | Short flag | Description | | :----------------------- | :--------- | :-------------------------------------------------------------- | | `--index-name` | `-i` | Name of index to configure (required) | | `--deletion-protection` | | Enable or disable deletion protection - `enabled` or `disabled` | | `--tags` | | Custom user tags (key=value pairs) | | `--json` | `-j` | Output in JSON format | | **Dedicated read nodes** | | | | `--read-mode` | | Read capacity mode - `ondemand` or `dedicated` | | `--read-node-type` | | Node type for dedicated read - `b1` or `t1` | | `--read-shards` | | Number of shards for dedicated read capacity | | `--read-replicas` | | Number of replicas for dedicated read capacity | | **Integrated embedding** | | | | `--model` | | Embedding model name | | `--field-map` | | Field mapping for embedding (key=value pairs) | | `--read-parameters` | | Read parameters for embedding model (key=value pairs) | | `--write-parameters` | | Write parameters for embedding model (key=value pairs) | | **Pods** | | | | `--pod-type` | `-t` | Type of pod to use; can only upgrade when configuring | | `--replicas` | `-r` | Number of replicas of the index to configure | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Enable deletion protection pc index configure --index-name my-index --deletion-protection enabled # Add tags pc index configure --index-name my-index --tags environment=production,team=ml # Switch to dedicated read capacity pc index configure --index-name my-index \ --read-mode dedicated \ --read-node-type b1 \ --read-shards 2 \ --read-replicas 2 # Verify changes pc index describe --index-name my-index ``` Configuration changes may take some time to take effect. **Description** Creates a new index in your Pinecone project. Supports serverless, pod-based, integrated (with embedding model), and BYOC (Bring Your Own Cloud) index types. **Usage** ```bash theme={null} pc index create [flags] ``` **Flags** | Long flag | Short flag | Description | | :----------------------- | :--------- | :----------------------------------------------------------------------------- | | `--name` | `-n` | Index name (required) | | `--dimension` | `-d` | Vector dimension (required for standard indexes, optional for integrated) | | `--metric` | `-m` | Similarity metric - `cosine`, `euclidean`, or `dotproduct` (default: `cosine`) | | `--cloud` | `-c` | Cloud provider - `aws`, `gcp`, or `azure` | | `--region` | `-r` | Cloud region | | `--vector-type` | `-v` | Vector type - `dense` or `sparse` (serverless only) | | `--source-collection` | | Name of the source collection from which to create the index | | `--schema` | | Metadata schema to control which fields are indexed (comma-separated) | | `--deletion-protection` | | Deletion protection - `enabled` or `disabled` | | `--tags` | | Custom user tags (key=value pairs) | | `--json` | `-j` | Output in JSON format | | **Integrated indexes** | | | | `--model` | | Integrated embedding model name | | `--field-map` | | Field mapping for integrated embedding (key=value pairs) | | `--read-parameters` | | Read parameters for embedding model (key=value pairs) | | `--write-parameters` | | Write parameters for embedding model (key=value pairs) | | **BYOC indexes** | | | | `--byoc-environment` | | BYOC environment to use for the index | | **Dedicated read nodes** | | | | `--read-mode` | | Read capacity mode - `ondemand` or `dedicated` (default: `ondemand`) | | `--read-node-type` | | Node type for dedicated read - `b1` or `t1` | | `--read-shards` | | Number of shards (each shard provides 250 GB storage) | | `--read-replicas` | | Number of replicas for higher throughput | | **Pod-based indexes** | | | | `--environment` | | Environment of the index to create (for example, `us-east-1-aws`) | | `--pod-type` | | Type of pod to use (for example, `p1.x1`, `s1.x2`) | | `--shards` | | Number of shards (default: `1`) | | `--replicas` | | Number of replicas (default: `1`) | | `--metadata-config` | | Comma-separated list of metadata fields to index for search | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Create serverless index pc index create -n my-index -d 1536 -m cosine -c aws -r us-east-1 # Create sparse vector index pc index create -n sparse-index -m dotproduct -c aws -r us-east-1 --vector-type sparse # With integrated embedding model pc index create \ -n my-index \ -m cosine \ -c aws \ -r us-east-1 \ --model multilingual-e5-large \ --field-map text=chunk_text # With dedicated read capacity pc index create \ -n my-index \ -d 1536 \ -m cosine \ -c aws \ -r us-east-1 \ --read-mode dedicated \ --read-node-type b1 \ --read-shards 2 \ --read-replicas 2 # With deletion protection pc index create \ -n my-index \ -d 1536 \ -m cosine \ -c aws \ -r us-west-2 \ --deletion-protection enabled # From collection pc index create \ -n my-index \ -d 1536 \ -m cosine \ -c aws \ -r eu-west-1 \ --source-collection my-collection # Create pod-based index pc index create \ -n my-index \ -d 1536 \ -m cosine \ --environment us-east-1-aws \ --pod-type p1.x1 \ --shards 1 \ --replicas 1 ``` For a list of valid regions for a serverless index, see [Create a serverless index](/guides/index-data/create-an-index). **Description** Permanently deletes an index and all its data. This operation cannot be undone. **Usage** ```bash theme={null} pc index delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :--------------------------------------------------------- | | `--index-name` | `-i` | Name of index to delete (required) | | `--skip-confirmation` | | Skip the deletion confirmation prompt | | `--json` | `-j` | Output in JSON format (also skips the confirmation prompt) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete an index (prompts for confirmation) pc index delete --index-name my-index # Skip the confirmation prompt pc index delete --index-name my-index --skip-confirmation # List before and after pc index list pc index delete --index-name test-index --skip-confirmation pc index list ``` This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. **Description** Displays detailed configuration and status information for a specific index. **Usage** ```bash theme={null} pc index describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :-------------------- | | `--index-name` | `-i` | Index name (required) | | `--json` | `-j` | Output in JSON format | The `--name`/`-n` flag is a deprecated alias for `--index-name`/`-i`. **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe an index pc index describe -i my-index # JSON output pc index describe -i my-index -j # Check newly created index pc index create -n test-index -d 1536 -m cosine -c aws -r us-east-1 pc index describe -i test-index ``` **Description** Displays statistics for an index, including total vector count and namespace breakdown. Optionally filter results with a metadata filter. **Usage** ```bash theme={null} pc index stats [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--filter` | `-f` | Metadata filter (inline JSON, `./path.json`, or `-` for stdin) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Get stats for an index pc index stats -i my-index # Get stats with a metadata filter pc index stats -i my-index --filter '{"genre":{"$eq":"rock"}}' # Filter from file pc index stats -i my-index --filter ./filter.json # JSON output pc index stats -i my-index -j ``` **Description** Displays all indexes in your current target project, including various details. **Usage** ```bash theme={null} pc index list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------------------------------------- | | `--json` | `-j` | Output in JSON format (includes full index details) | | `--wide` | `-w` | Show additional columns (host, embed, tags) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all indexes pc index list # Show additional details pc index list --wide # JSON output for scripting pc index list -j # After creating indexes pc index create -n test-1 -d 768 -m cosine -c aws -r us-east-1 pc index list ``` ### Namespaces **Description** Creates a new namespace within an index. Namespaces allow you to partition vectors within an index. **Usage** ```bash theme={null} pc index namespace create [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :-------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--name` | | Namespace name (required) | | `--schema` | | Metadata schema for the namespace (comma-separated) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Create a namespace pc index namespace create -i my-index --name tenant-a # Create with metadata schema (comma-separated list of filterable metadata fields) pc index namespace create -i my-index --name tenant-b --schema "category,brand" # JSON output pc index namespace create -i my-index --name tenant-c -j ``` **Description** Deletes a namespace and all its vectors from an index. This operation cannot be undone. **Usage** ```bash theme={null} pc index namespace delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :--------------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--name` | | Namespace name (required); use `__default__` for the default namespace | | `--skip-confirmation` | | Skip the deletion confirmation prompt | | `--json` | `-j` | Output in JSON format (also skips the confirmation prompt) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete a namespace (prompts for confirmation) pc index namespace delete -i my-index --name tenant-a # Delete the default namespace pc index namespace delete -i my-index --name __default__ # Skip the confirmation prompt pc index namespace delete -i my-index --name tenant-a --skip-confirmation ``` Deleting a namespace removes all vectors in that namespace. This operation cannot be undone. **Description** Displays detailed information about a specific namespace, including record count and schema configuration. **Usage** ```bash theme={null} pc index namespace describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :--------------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--name` | | Namespace name (required); use `__default__` for the default namespace | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe a namespace pc index namespace describe -i my-index --name tenant-a # Describe the default namespace pc index namespace describe -i my-index --name __default__ # JSON output pc index namespace describe -i my-index --name tenant-a -j ``` **Description** Lists all namespaces within an index, including vector counts. **Usage** ```bash theme={null} pc index namespace list [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :----------------------------- | | `--index-name` | `-i` | Index name (required) | | `--limit` | `-l` | Maximum number of results | | `--pagination-token` | `-p` | Pagination token for next page | | `--prefix` | | Filter namespaces by prefix | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all namespaces pc index namespace list -i my-index # Filter by prefix pc index namespace list -i my-index --prefix "tenant-" # Limit results pc index namespace list -i my-index --limit 10 # JSON output pc index namespace list -i my-index -j ``` ### Vectors **Description** Deletes vectors from an index by ID, filter, or deletes all vectors in a namespace. **Usage** ```bash theme={null} pc index vector delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :------------------------------------------------------------------------ | | `--index-name` | `-i` | Index name (required) | | `--namespace` | | Namespace to delete from (default: `__default__`) | | `--ids` | | Vector IDs to delete (inline JSON array, `./path.json`, or `-` for stdin) | | `--filter` | | Metadata filter (inline JSON, `./path.json`, or `-` for stdin) | | `--all-vectors` | | Delete all vectors in the namespace | | `--skip-confirmation` | | Skip the confirmation prompt shown for `--all-vectors` | | `--json` | `-j` | Output in JSON format (also skips the confirmation prompt) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete specific vectors pc index vector delete -i my-index --ids '["id1"]' # Delete multiple vectors (inline JSON array, or JSON array in a file) pc index vector delete -i my-index --ids '["id1", "id2"]' # Delete by filter pc index vector delete -i my-index --filter '{"genre":"classical"}' # Delete all vectors in a namespace (prompts for confirmation) pc index vector delete -i my-index --namespace old-data --all-vectors # Delete all vectors without the prompt pc index vector delete -i my-index --namespace old-data --all-vectors --skip-confirmation ``` Only `--all-vectors` prompts for confirmation. Targeted deletes with `--ids` or `--filter` proceed without a prompt. Pass `--skip-confirmation` (or `--json`) to bypass the `--all-vectors` prompt. Vector deletion is permanent and cannot be undone. **Description** Retrieves vectors by their IDs or by a metadata filter, returning the vector values and metadata. **Usage** ```bash theme={null} pc index vector fetch [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :----------------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--namespace` | | Namespace to fetch from (default: `__default__`) | | `--ids` | | Vector IDs to fetch (inline JSON array, `./path.json`, or `-` for stdin) | | `--filter` | `-f` | Metadata filter (inline JSON, `./path.json`, or `-` for stdin) | | `--limit` | `-l` | Maximum number of vectors to fetch | | `--pagination-token` | `-p` | Pagination token for next page | | `--body` | | Request body JSON (inline, `./path.json`, or `-` for stdin) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Fetch specific vectors by ID pc index vector fetch -i my-index --ids '["123","456","789"]' # Fetch from a file pc index vector fetch -i my-index --ids ./ids.json # Fetch by metadata filter pc index vector fetch -i my-index --filter '{"genre":{"$eq":"rock"}}' # Fetch from a namespace pc index vector fetch -i my-index --namespace tenant-a --ids '["doc-123"]' # JSON output pc index vector fetch -i my-index --ids '["vec1"]' -j ``` Use either `--ids` or `--filter`, not both. When using `--ids`, pagination flags are not applicable. **Description** Lists vector IDs in a namespace with optional pagination. **Usage** ```bash theme={null} pc index vector list [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :---------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--namespace` | | Namespace to list from (default: `__default__`) | | `--limit` | `-l` | Maximum number of IDs to return | | `--pagination-token` | `-p` | Pagination token for next page | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List vector IDs pc index vector list -i my-index # List from a namespace with limit pc index vector list -i my-index --namespace tenant-a --limit 50 # JSON output pc index vector list -i my-index -j ``` **Description** Queries an index for similar vectors using dense vectors, sparse vectors, or vector ID. **Usage** ```bash theme={null} pc index vector query [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :-------------------------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--namespace` | | Namespace to query (default: `__default__`) | | `--id` | | Query by vector ID | | `--vector` | `-v` | Query vector values (inline JSON array, `./path.json`, or `-` for stdin) | | `--sparse-indices` | | Sparse vector indices (inline JSON uint32 array, `./path.json`, or `-` for stdin) | | `--sparse-values` | | Sparse vector values (inline JSON array, `./path.json`, or `-` for stdin) | | `--top-k` | `-k` | Number of results to return (default: 10) | | `--filter` | `-f` | Metadata filter (inline JSON, `./path.json`, or `-` for stdin) | | `--include-values` | | Include vector values in results | | `--include-metadata` | | Include metadata in results | | `--body` | | Request body JSON (inline, `./path.json`, or `-` for stdin) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Query by vector ID pc index vector query -i my-index --id "doc-123" -k 10 --include-metadata # Query by vector values pc index vector query -i my-index --vector '[0.1, 0.2, 0.3]' -k 25 # Query with metadata filter pc index vector query -i my-index \ --vector '[0.1, 0.2, 0.3]' \ --filter '{"genre":{"$eq":"sci-fi"}}' \ --include-metadata # Query from file (file contains a JSON array that specifies the query vector) pc index vector query -i my-index --vector ./embedding.json -k 20 # Query with sparse vectors (inline) pc index vector query -i my-index \ --sparse-indices '[0, 5, 12]' \ --sparse-values '[0.5, 0.3, 0.8]' \ -k 15 # Query with sparse vectors from files # indices.json: [0, 5, 12] # values.json: [0.5, 0.3, 0.8] pc index vector query -i my-index \ --sparse-indices ./indices.json \ --sparse-values ./values.json \ -k 15 # Query from stdin (extract embedding from a document) # doc.json: {"id": "doc-123", "embedding": [0.1, 0.2, 0.3], "text": "..."} jq -c '.embedding' doc.json | pc index vector query -i my-index --vector - -k 10 ``` Use `--id`, `--vector`, or sparse vectors (`--sparse-indices` and `--sparse-values`) to specify what to query against. These options are mutually exclusive. **Description** Updates a vector's values, sparse values, or metadata by ID, or updates metadata for multiple vectors matching a filter. **Usage** ```bash theme={null} pc index vector update [flags] ``` **Flags** | Long flag | Short flag | Description | | :----------------- | :--------- | :----------------------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--namespace` | | Namespace containing the vector (default: `__default__`) | | `--id` | | Vector ID to update | | `--values` | | New vector values (inline JSON array, `./path.json`, or `-` for stdin) | | `--sparse-indices` | | New sparse indices (inline JSON uint32 array, `./path.json`, or `-` for stdin) | | `--sparse-values` | | New sparse values (inline JSON array, `./path.json`, or `-` for stdin) | | `--metadata` | | New or updated metadata (inline JSON, `./path.json`, or `-` for stdin) | | `--filter` | | Metadata filter for bulk update (inline JSON, `./path.json`, or `-` for stdin) | | `--dry-run` | | Preview how many records would be updated without applying changes | | `--body` | | Request body JSON (inline, `./path.json`, or `-` for stdin) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Update metadata for a single vector pc index vector update -i my-index --id "vec1" --metadata '{"category":"updated"}' # Update values for a single vector pc index vector update -i my-index --id "vec1" --values '[0.2, 0.3, 0.4]' # Update sparse values # indices.json: [0, 5, 12] # values.json: [0.5, 0.3, 0.8] pc index vector update -i my-index --id "vec1" \ --sparse-indices ./indices.json \ --sparse-values ./values.json # Bulk update metadata by filter (preview first) pc index vector update -i my-index \ --filter '{"genre":{"$eq":"sci-fi"}}' \ --metadata '{"genre":"fantasy"}' \ --dry-run # Apply the bulk update pc index vector update -i my-index \ --filter '{"genre":{"$eq":"sci-fi"}}' \ --metadata '{"genre":"fantasy"}' ``` Use either `--id` for single vector updates or `--filter` for bulk updates. These options are mutually exclusive. **Description** Inserts or updates vectors in an index from a JSON or JSONL file, or inline JSON. The CLI automatically batches vectors for efficient uploading. Files can contain any number of vectors—the CLI splits them into batches and sends multiple API requests as needed. **Usage** ```bash theme={null} pc index vector upsert [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :--------------------------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--namespace` | | Namespace to upsert into (default: `__default__`) | | `--body` | | Request body JSON or JSONL (inline, `./path.json[l]`, or `-` for stdin) (required) | | `--batch-size` | `-b` | Size of batches to upsert (default: 500) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Upsert from JSON file (with "vectors" array) # vectors.json: {"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]} pc index vector upsert -i my-index --body ./vectors.json # Upsert with inline JSON pc index vector upsert -i my-index --body '{"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]}' # Upsert from JSONL file (one vector per line) # vectors.jsonl: {"id": "vec1", "values": [0.1, 0.2, 0.3]} # {"id": "vec2", "values": [0.4, 0.5, 0.6]} pc index vector upsert -i my-index --body ./vectors.jsonl # Upsert from stdin (same format as JSON or JSONL file) cat vectors.json | pc index vector upsert -i my-index --body - # Custom batch size (default: 500, max: 1000 per API request) pc index vector upsert -i my-index --body ./vectors.json --batch-size 1000 ``` **Batch size limits:** The API accepts up to 1000 vectors per request. The CLI defaults to batches of 500 vectors, but you can adjust this with `--batch-size` (up to 1000). Large files are automatically split into multiple batches. **File size:** There's no explicit file size limit—the CLI reads the entire file into memory and batches it automatically. Very large files are supported as long as they fit in available system memory. ### Records **Description** Search an index namespace with a query text, query vector, or record ID and return the most similar records, along with their similarity scores. Optionally, rerank the initial results based on their relevance to the query. Searching with text is supported only for indexes with an integrated embedding configured. Searching with a query vector or record ID is supported for all indexes. Exactly one primary query mode must be provided: * `--inputs` — query text (requires an index with integrated embedding) * `--id` — use an existing record's vector as the query * `--vector` — provide a dense vector directly (all index types) * `--sparse-indices` + `--sparse-values` — sparse vector (all index types) Combine `--vector` with `--sparse-indices`/`--sparse-values` for hybrid search. Use `--body` to pass a full request object; flags take precedence over `--body` when both specify the same field. **Usage** ```bash theme={null} pc index record search [flags] ``` **Flags** | Long flag | Short flag | Description | | :----------------- | :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--index-name` | `-i` | Name of the index to search (required) | | `--inputs` | | Query inputs for text search (inline JSON, `./path.json`, or `-` for stdin); requires integrated embedding. Mutually exclusive with `--id` and `--vector`. | | `--id` | | Use an existing record's vector by ID for the query. Mutually exclusive with `--inputs` and `--vector`. | | `--vector` | `-v` | Dense vector values to search against (inline JSON float32 array, `./path.json`, or `-` for stdin). Mutually exclusive with `--inputs` and `--id`. | | `--sparse-indices` | | Sparse vector indices (inline JSON int32 array, `./path.json`, or `-` for stdin). Must be used together with `--sparse-values`. | | `--sparse-values` | | Sparse vector values (inline JSON float32 array, `./path.json`, or `-` for stdin). Must be used together with `--sparse-indices`. | | `--top-k` | `-k` | Number of results to return (required) | | `--namespace` | | Namespace to search | | `--filter` | | Metadata filter (inline JSON, `./path.json`, or `-` for stdin) | | `--rerank` | | Re-score results using an inference model (inline JSON, `./path.json`, or `-` for stdin). Required fields: `model` (string), `rank_fields` (string array). | | `--match-terms` | | Keyword terms filter for sparse integrated indexes (inline JSON, `./path.json`, or `-` for stdin). Required field: `terms` (string array). Requires `--inputs`. | | `--fields` | | Fields to return in results (inline JSON string array, `./path.json`, or `-` for stdin) | | `--body` | | Full request body JSON (inline, `./path.json`, or `-` for stdin). Flags take precedence when both specify the same field. | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Examples** ```bash theme={null} # Text search (integrated embedding indexes only) pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --top-k 10 pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --namespace my-namespace --top-k 5 pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --filter '{"category":"health"}' --top-k 10 pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --fields '["_id","chunk_text","category"]' --top-k 10 pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --rerank '{"model":"bge-reranker-v2-m3","rank_fields":["chunk_text"]}' --top-k 10 pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --match-terms '{"terms":["vaccine","prevention"]}' --top-k 10 # Search by record ID for query vector (all index types) pc index record search --index-name my-index --id rec-123 --top-k 10 # Vector search (all index types) pc index record search --index-name my-index --vector '[0.1,0.2,0.3]' --top-k 10 pc index record search --index-name my-index --sparse-indices '[1,5,9]' --sparse-values '[0.4,0.8,0.2]' --top-k 10 pc index record search --index-name my-index --vector '[0.1,0.2,0.3]' --sparse-indices '[1,5,9]' --sparse-values '[0.4,0.8,0.2]' --top-k 10 # Full request body (must include top_k in the body) pc index record search --index-name my-index --body ./search.json ``` ```text CLI theme={null} Usage: 5 (read units) ID SCORE FIELDS rec-001 0.912340 {"category":"health","chunk_text":"vaccine research..."} rec-002 0.887210 {"category":"health","chunk_text":"disease prevention..."} ``` **Description** Upsert records into an integrated index namespace from a JSON or JSONL payload. The `--body` flag accepts a JSON object containing a `"records"` array of `IntegratedRecord` objects, a raw JSON array of records, or a JSONL stream of records (one object per line). The value can be inline JSON, a path to a `.json` or `.jsonl` file, or `-` to read from stdin. Records are sent in batches. The default batch size is 96 (the API maximum). Use `--batch-size` to send smaller batches. **Usage** ```bash theme={null} pc index record upsert [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :-------------------------------------------------------------------------------------- | | `--index-name` | `-i` | Name of the index to upsert into (required) | | `--body` | | Request body JSON or JSONL (inline JSON, `./path.json[l]`, or `-` for stdin) (required) | | `--namespace` | | Namespace to upsert into | | `--batch-size` | `-b` | Number of records per batch (default: `96`, max: `96`) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Examples** ```bash theme={null} # Upsert from a JSON file pc index record upsert --index-name my-index --body ./records.json # Upsert from a JSONL file into a specific namespace pc index record upsert --index-name my-index --namespace my-namespace --body ./records.jsonl # Upsert from stdin cat records.jsonl | pc index record upsert --index-name my-index --namespace my-namespace --body - ``` ### Collections **Description** Creates a static copy of a pod-based index as a collection. Collections can be used to store a snapshot of an index's data for backup or migration purposes. **Usage** ```bash theme={null} pc index collection create [flags] ``` **Flags** | Long flag | Short flag | Description | | :--------- | :--------- | :---------------------------------------------------------- | | `--name` | `-n` | Name to give the collection (required) | | `--source` | `-s` | Name of the pod-based index to use as the source (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Create a collection from a pod-based index pc index collection create --name my-collection --source my-index ``` ```text CLI theme={null} ATTRIBUTE VALUE Name my-collection State Initializing Dimension 1536 Size 0 VectorCount 0 Environment us-east-1-aws ``` **Description** Deletes a collection permanently. This action cannot be undone. **Usage** ```bash theme={null} pc index collection delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :--------------------------------------------------------- | | `--name` | `-n` | Name of the collection to delete (required) | | `--skip-confirmation` | | Skip the deletion confirmation prompt | | `--json` | `-j` | Output in JSON format (also skips the confirmation prompt) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete a collection (prompts for confirmation) pc index collection delete --name my-collection # Skip the confirmation prompt pc index collection delete --name my-collection --skip-confirmation ``` This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. **Description** Returns detailed information about a single collection, including its state, dimension, size, vector count, and environment. **Usage** ```bash theme={null} pc index collection describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------------------------------- | | `--name` | `-n` | Name of the collection to describe (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe a collection pc index collection describe --name my-collection ``` ```text CLI theme={null} ATTRIBUTE VALUE Name my-collection State Ready Dimension 1536 Size 104857600 VectorCount 10000 Environment us-east-1-aws ``` **Description** Lists all collections in your current project, sorted alphabetically by name. **Usage** ```bash theme={null} pc index collection list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all collections pc index collection list ``` ```text CLI theme={null} NAME DIMENSION SIZE STATUS VECTORS ENVIRONMENT my-collection 1536 104857600 Ready 10000 us-east-1-aws ``` ### Backups **Description** Creates a backup of a serverless index. Backups are static copies that only consume storage. **Usage** ```bash theme={null} pc index backup create [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------- | :--------- | :------------------------------------------------------------------- | | `--index-name` | `-i` | Name of the index to back up (required) | | `--name` | | Human-readable label for the backup (the backup ID is always a UUID) | | `--description` | `-d` | Description for the backup | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Create a backup pc index backup create -i my-index # Create with name and description pc index backup create -i my-index --name "nightly-backup" -d "Nightly backup before deployment" # JSON output pc index backup create -i my-index -j ``` **Description** Permanently deletes a backup. This operation cannot be undone. **Usage** ```bash theme={null} pc index backup delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :--------------------------------------------------------- | | `--id` | `-i` | Backup ID to delete (required) | | `--skip-confirmation` | | Skip the deletion confirmation prompt | | `--json` | `-j` | Output in JSON format (also skips the confirmation prompt) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete a backup by ID (prompts for confirmation) pc index backup delete -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f # Skip the confirmation prompt pc index backup delete -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f --skip-confirmation ``` This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. Backup deletion is permanent and cannot be undone. **Description** Displays detailed information about a specific backup. **Usage** ```bash theme={null} pc index backup describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :------------------------------- | | `--id` | `-i` | Backup ID to describe (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe a backup pc index backup describe -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f # JSON output pc index backup describe -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -j ``` **Description** Lists backups in the current project, optionally filtered by index name. **Usage** ```bash theme={null} pc index backup list [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :----------------------------- | | `--index-name` | `-i` | Filter backups by index name | | `--limit` | `-l` | Maximum number of results | | `--pagination-token` | `-p` | Pagination token for next page | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all backups in the project pc index backup list # List backups for a specific index pc index backup list --index-name my-index # Limit results pc index backup list --limit 10 # JSON output pc index backup list -j ``` **Description** Creates a new index from a backup. **Usage** ```bash theme={null} pc index restore [flags] ``` **Flags** | Long flag | Short flag | Description | | :---------------------- | :--------- | :--------------------------------------------------- | | `--id` | `-i` | Backup ID (UUID) to restore from (required) | | `--name` | `-n` | Name for the new index (required) | | `--deletion-protection` | | Enable deletion protection - `enabled` or `disabled` | | `--tags` | `-t` | Tags to apply to the new index (key=value pairs) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Restore an index from a backup pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index # Restore with tags and deletion protection pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index \ --tags env=prod,team=search \ --deletion-protection enabled # JSON output pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index -j ``` **Description** Displays the status and details of a restore job. **Usage** ```bash theme={null} pc index restore describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :------------------------------------ | | `--id` | `-i` | Restore job ID to describe (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe a restore job pc index restore describe -i rj-abc123 # JSON output pc index restore describe -i rj-abc123 -j ``` **Description** Lists all restore jobs in the current project. **Usage** ```bash theme={null} pc index restore list [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :----------------------------- | | `--limit` | `-l` | Maximum number of results | | `--pagination-token` | `-p` | Pagination token for next page | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List restore jobs pc index restore list # Limit results pc index restore list --limit 10 # JSON output pc index restore list -j ``` ### Imports **Description** Start an import that loads vector data from a storage provider into a serverless index. The URI must begin with the scheme of a supported provider (for example, `s3://`). For private buckets, configure a storage integration in the Pinecone console and pass the integration ID with `--integration-id`. Use `--error-mode` to control behavior when records fail: `continue` skips failing records and keeps going; `abort` stops the import on first error. Defaults to `continue`. **Usage** ```bash theme={null} pc index import start [flags] ``` **Flags** | Long flag | Short flag | Description | | :----------------- | :--------- | :-------------------------------------------------------------------- | | `--index-name` | `-i` | Name of the index to import into (required) | | `--uri` | `-u` | URI of the data to import, for example `s3://bucket/path/` (required) | | `--integration-id` | | Storage integration ID for private buckets | | `--error-mode` | | How to handle record errors: `continue` (default) or `abort` | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Examples** ```bash theme={null} # Start an import from a public S3 bucket pc index import start --index-name my-index --uri s3://my-bucket/data/ # Start an import from a private bucket using a storage integration pc index import start --index-name my-index --uri s3://my-bucket/data/ --integration-id intg-123 # Abort on the first error instead of continuing pc index import start --index-name my-index --uri s3://my-bucket/data/ --error-mode abort # JSON output pc index import start --index-name my-index --uri s3://my-bucket/data/ -j ``` ```text CLI theme={null} Import imp-abc123 started. ATTRIBUTE VALUE Import ID imp-abc123 ``` **Description** Show the current status and details of an import operation, including percent complete, records imported, and any error messages. **Usage** ```bash theme={null} pc index import describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :------------------------------------------------- | | `--index-name` | `-i` | Name of the index the import belongs to (required) | | `--id` | | ID of the import to describe (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe an import operation pc index import describe --index-name my-index --id import-123 # JSON output pc index import describe --index-name my-index --id import-123 -j ``` ```text CLI theme={null} ATTRIBUTE VALUE Import ID import-123 Status InProgress URI s3://my-bucket/data/ Percent Complete 45.0% Records Imported 450 Created At 2024-01-15 12:00:00 Finished At - Error None ``` **Description** List bulk import operations for the given index, with optional pagination. **Usage** ```bash theme={null} pc index import list [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :-------------------------------------------------------- | | `--index-name` | `-i` | Name of the index to list imports for (required) | | `--limit` | `-l` | Maximum number of imports to return | | `--pagination-token` | `-p` | Pagination token to continue a previous listing operation | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Examples** ```bash theme={null} # List all imports for an index pc index import list --index-name my-index # List imports with a page size limit pc index import list --index-name my-index --limit 10 # Continue paginating from a previous call pc index import list --index-name my-index --pagination-token eyJ... # JSON output pc index import list --index-name my-index -j ``` ```text CLI theme={null} IMPORT ID STATUS URI PERCENT RECORDS CREATED FINISHED imp-abc123 Completed s3://my-bucket/data/ 100.0% 1000 2024-01-15 12:00:00 2024-01-15 12:05:00 imp-def456 InProgress s3://other-bucket/data/ 45.0% 450 2024-01-15 13:00:00 - ``` **Description** Cancel an import operation that is currently pending or in progress. Already-completed or failed imports cannot be canceled. **Usage** ```bash theme={null} pc index import cancel [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :------------------------------------------------- | | `--index-name` | `-i` | Name of the index the import belongs to (required) | | `--id` | | ID of the import to cancel (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Cancel an import operation pc index import cancel --index-name my-index --id import-123 # JSON output pc index import cancel --index-name my-index --id import-123 -j ``` ```text CLI theme={null} Import import-123 canceled. ``` ### Projects **Description** Creates a new project in your [target organization](/reference/cli/target-context), using the specified configuration. **Usage** ```bash theme={null} pc project create [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :------------------------------------------------------------- | | `--force-encryption` | | Enable encryption with CMEK | | `--json` | `-j` | Output in JSON format | | `--name` | `-n` | Project name (required) | | `--target` | | Automatically target the project in the CLI after it's created | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Basic project creation pc project create -n "demo-project" ``` **Description** Permanently deletes a project and all its resources. This operation cannot be undone. **Usage** ```bash theme={null} pc project delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :---------------------------------------------------------- | | `--id` | `-i` | Project ID (optional, uses target project if not specified) | | `--json` | `-j` | Output in JSON format | | `--skip-confirmation` | | Skip confirmation prompt | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete target project pc project delete # Delete specific project pc project delete -i proj-abc123 # Skip confirmation pc project delete -i proj-abc123 --skip-confirmation ``` Must delete all indexes and collections in the project first. If the deleted project is your current target, set a new target after deleting it. **Description** Displays detailed information about a specific project, including various details. **Usage** ```bash theme={null} pc project describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--id` | `-i` | Project ID (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe a project pc project describe -i proj-abc123 # JSON output pc project describe -i proj-abc123 --json # Find ID and describe pc project list pc project describe -i proj-abc123 ``` **Description** Displays all projects in your [target organization](/reference/cli/target-context), including various details. **Usage** ```bash theme={null} pc project list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all projects pc project list # JSON output pc project list --json # List after login pc auth login pc auth target -o "my-org" pc project list ``` **Description** Modifies the configuration of the [target project](/reference/cli/target-context), or a specific project ID. **Usage** ```bash theme={null} pc project update [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :---------------------------------- | | `--force-encryption` | `-f` | Enable/disable encryption with CMEK | | `--id` | `-i` | Project ID (required) | | `--json` | `-j` | Output in JSON format | | `--name` | `-n` | New project name | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Update name pc project update -i proj-abc123 -n "new-name" ``` ### Organizations **Description** Permanently deletes an organization and all its resources. This operation cannot be undone. **Usage** ```bash theme={null} pc organization delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :------------------------- | | `--id` | `-i` | Organization ID (required) | | `--json` | `-j` | Output in JSON format | | `--skip-confirmation` | | Skip confirmation prompt | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete an organization pc organization delete -i org-abc123 # Skip confirmation pc organization delete -i org-abc123 --skip-confirmation ``` This is a highly destructive action. Deletion is permanent. If the deleted organization is your current [target](/reference/cli/target-context), set a new target after deleting. **Description** Displays detailed information about a specific organization, including name, ID, creation date, payment status, plan, and support tier. **Usage** ```bash theme={null} pc organization describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :------------------------- | | `--id` | `-i` | Organization ID (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe an organization pc organization describe -i org-abc123 # JSON output pc organization describe -i org-abc123 --json # Find ID and describe pc organization list pc organization describe -i org-abc123 ``` **Description** Displays all organizations that the authenticated user has access to, including name, ID, creation date, payment status, plan, and support tier. **Usage** ```bash theme={null} pc organization list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all organizations pc organization list # JSON output pc organization list --json # List after login pc auth login pc organization list ``` **Description** Modifies the configuration of the [target organization](/reference/cli/target-context), or a specific organization ID. **Usage** ```bash theme={null} pc organization update [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :------------------------- | | `--id` | `-i` | Organization ID (required) | | `--json` | `-j` | Output in JSON format | | `--name` | `-n` | New organization name | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Update name pc organization update -i org-abc123 -n "new-name" # Verify changes pc organization update -i org-abc123 -n "Acme Corp" pc organization describe -i org-abc123 ``` ### API keys **Description** Creates a new API key for the current [target project](/reference/cli/target-context) or a specific project ID. Optionally stores the key locally for CLI use. **Usage** ```bash theme={null} pc api-key create [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------------------------------------------------------------------------- | | `--id` | `-i` | Project ID (optional, uses target project if not specified) | | `--json` | `-j` | Output in JSON format | | `--name` | `-n` | Key name (required) | | `--roles` | | Roles to assign (default: `ProjectEditor`) | | `--store` | | Store the key locally for CLI use (automatically replaces any existing CLI-managed key) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Basic key creation pc api-key create -n "my-key" # Create and store locally pc api-key create -n "my-key" --store # Create with specific role pc api-key create -n "my-key" --store --roles ProjectEditor # Create for specific project pc api-key create -n "my-key" -i proj-abc123 ``` API keys are scoped to a specific organization and project. **Description** Permanently deletes an API key. Applications using this key immediately lose access. **Usage** ```bash theme={null} pc api-key delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :----------------------- | | `--id` | `-i` | API key ID (required) | | `--skip-confirmation` | | Skip confirmation prompt | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete an API key pc api-key delete -i key-abc123 # Skip confirmation pc api-key delete -i key-abc123 --skip-confirmation # Delete and clean up local storage pc api-key delete -i key-abc123 pc auth local-keys prune --skip-confirmation ``` Deletion is permanent. Applications using this key immediately lose access to Pinecone. **Description** Displays detailed information about a specific API key, including its name, ID, project ID, and roles. **Usage** ```bash theme={null} pc api-key describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--id` | `-i` | API key ID (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe an API key pc api-key describe -i key-abc123 # JSON output pc api-key describe -i key-abc123 --json # Find ID and describe pc api-key list pc api-key describe -i key-abc123 ``` Does not display the actual key value. **Description** Displays a list of all of the [target project's](/reference/cli/target-context) API keys, as found in Pinecone (regardless of whether they are stored locally by the CLI). Displays various details about each key, including name, ID, project ID, and roles. **Usage** ```bash theme={null} pc api-key list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :---------------------------------------------------------- | | `--id` | `-i` | Project ID (optional, uses target project if not specified) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List keys for target project pc api-key list # List for specific project pc api-key list -i proj-abc123 # JSON output pc api-key list --json ``` Does not display key values. **Description** Updates the name and roles of an API key. **Usage** ```bash theme={null} pc api-key update [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--id` | `-i` | API key ID (required) | | `--json` | `-j` | Output in JSON format | | `--name` | `-n` | New key name | | `--roles` | `-r` | Roles to assign | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Update name pc api-key update -i key-abc123 -n "new-name" # Update roles pc api-key update -i key-abc123 -r ProjectEditor # Verify changes pc api-key update -i key-abc123 -n "production-key" pc api-key describe -i key-abc123 ``` Cannot change the actual key. If you need a different key, create a new one. ### Config **Description** Lists all CLI configuration settings and their current values. Sensitive values like `api-key` are masked by default; use `--reveal` to see the full value. Hidden settings such as `environment` are included when `--all` is passed. **Usage** ```bash theme={null} pc config list [flags] ``` **Flags** | Long flag | Short flag | Description | | :--------- | :--------- | :-------------------------------------------------------- | | `--reveal` | | Reveal the full value for sensitive settings like api-key | | `--json` | `-j` | Output in JSON format | | `--all` | | Include hidden settings such as environment | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc config list pc config list --all pc config list --reveal pc config list --json ``` ```text CLI theme={null} KEY VALUE ENV VAR NAME ENV VAR OVERRIDE DESCRIPTION api-key ****abcd**** PINECONE_API_KEY false Default API key for authenticating with Pinecone color true Enable colored output ``` **Description** Gets the current value of a configuration setting. Valid keys are: `api-key`, `color`, `environment`. Sensitive values like `api-key` are masked by default; use `--reveal` to see the full value. **Usage** ```bash theme={null} pc config get [flags] ``` **Flags** | Long flag | Short flag | Description | | :--------- | :--------- | :-------------------------------------------------------- | | `--reveal` | | Reveal the full value for sensitive settings like api-key | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc config get api-key pc config get api-key --reveal pc config get environment pc config get color ``` **Description** Displays detailed information about a specific CLI configuration setting, including its current value, whether an environment variable is overriding it, and valid values. Valid keys are: `api-key`, `color`, `environment`. **Usage** ```bash theme={null} pc config describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :--------- | :--------- | :-------------------------------------------------------- | | `--reveal` | | Reveal the full value for sensitive settings like api-key | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc config describe api-key pc config describe color pc config describe color --json ``` ```text CLI theme={null} KEY api-key VALUE ****abcd**** ENV VAR NAME $PINECONE_API_KEY ENV VAR OVERRIDE false SENSITIVE true DESCRIPTION Default API key for authenticating with Pinecone ``` **Description** Sets a CLI configuration value. Valid keys are: `api-key`, `color`, `environment`. The value is persisted to the local config file. **Usage** ```bash theme={null} pc config set [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc config set api-key pcsk_... pc config set environment staging pc config set color false ``` **Description** Resets a CLI configuration value to its default. Valid keys are: `api-key`, `color`, `environment`. **Usage** ```bash theme={null} pc config unset [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc config unset api-key pc config unset color ``` # CLI quickstart Source: https://docs.pinecone.io/reference/cli/quickstart Pinecone CLI quickstart for installing pc, authenticating, and managing indexes, vectors, and data imports directly from your terminal. The Pinecone CLI (`pc`) lets you manage Pinecone resources directly from your terminal. ## Install ```bash theme={null} brew tap pinecone-io/tap brew install pinecone-io/tap/pinecone ``` Pre-built binaries for macOS, Linux, and Windows are available on the [GitHub Releases page](https://github.com/pinecone-io/cli/releases). | Platform | Architectures | | :------- | :------------------------------------- | | macOS | Intel (x86\_64), Apple Silicon (ARM64) | | Linux | x86\_64, ARM64, i386 | | Windows | x86\_64, i386 | ## Authenticate ```bash theme={null} pc auth login ``` Visit the URL in your terminal to sign in. The CLI automatically sets your default organization and project. To target a different org/project: ```bash theme={null} pc target -o "my-org" -p "my-project" ``` For CI/CD or automation, you can also authenticate with a [service account](/reference/cli/authentication#service-account) or [API key](/reference/cli/authentication#api-key). ## Manage indexes ```bash theme={null} # List indexes pc index list # Create an index pc index create -n my-index -d 3 -m cosine -c aws -r us-east-1 # Get index details pc index describe -i my-index # Get index statistics pc index stats -i my-index ``` ## Work with vectors ```bash theme={null} # Upsert vectors (from file or inline JSON) pc index vector upsert -i my-index \ --body '{"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]}' # Import from a large dataset in object storage (S3, GCS, Azure) pc index import start -i my-index --uri s3://my-bucket/data/ # Check the progress of an import operation pc index import list --i my-index pc index import describe --i my-index --id import-123 # Query (vector can be inline or in a file) pc index vector query -i my-index \ --vector '[0.1, 0.2, 0.3]' \ --top-k 10 \ --include-metadata # Fetch by ID (from file or inline JSON) pc index vector fetch -i my-index --ids '["vec1","vec2"]' # List vector IDs from an index pc index vector list -i my-index ``` ## Manage namespaces ```bash theme={null} # List namespaces pc index namespace list -i my-index # Create a namespace pc index namespace create -i my-index --name tenant-a # Delete a namespace pc index namespace delete -i my-index --name tenant-a ``` ## Back up and restore ```bash theme={null} # Create a backup pc index backup create -i my-index --name "my-index-backup" # List backups (show index, backup name, backup ID, etc.) pc index backup list -i my-index # Restore from backup (by ID, not name) pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index ``` ## JSON output Add `-j` to any command for JSON output: ```bash theme={null} pc index list -j pc index describe -i my-index -j ``` ## Getting help Use `-h` or `--help` with any command to see available options: ```bash theme={null} pc -h pc index -h pc index create -h ``` ## Next steps * [Command reference](/reference/cli/command-reference) — Full list of commands and flags * [Authentication](/reference/cli/authentication) — Service accounts, API keys, and auth priority * [Target context](/reference/cli/target-context) — How org/project targeting works # CLI target context Source: https://docs.pinecone.io/reference/cli/target-context Pinecone CLI: The CLI's **target context** determines which organization and project your commands operate on. You must authenticate before setting target. The CLI's **target context** determines which organization and project your commands operate on. You must [authenticate](/reference/cli/authentication) before setting target context. ## Flags | Flag | Short | Default | Description | | ------------------- | ----- | ------- | --------------------------------------------------------------------------------- | | `--org` | `-o` | — | Target organization by name. Mutually exclusive with `--organization-id`. | | `--organization-id` | — | — | Target organization by ID. Mutually exclusive with `--org`. | | `--project` | `-p` | — | Target project by name. Mutually exclusive with `--project-id`. | | `--project-id` | — | — | Target project by ID. Mutually exclusive with `--project`. | | `--show` | `-s` | `false` | Show the current target context. | | `--clear` | — | `false` | Clear the stored target context. | | `--json` | `-j` | `false` | Output as JSON. In non-TTY environments (CI/CD, pipes), JSON output is automatic. | `--org` and `--organization-id` are mutually exclusive — use one or the other. The same applies to `--project` and `--project-id`. ## How operations use target context | Operation type | Scope | | -------------------------------- | ---------------------------------------- | | Control plane (indexes, backups) | Target project | | Data plane (vectors, namespaces) | Target project + specified index | | Admin API (organizations) | No target context needed | | Admin API (projects) | Target organization | | Admin API (API keys) | Target project (unless `--id` specified) | ## Target context by auth method ### User login After `pc auth login`, the CLI auto-targets your default organization and its first project. ```bash theme={null} # Change target pc target -o "my-org" -p "my-project" ``` ### Service account **Via CLI command:** After `pc auth configure --client-id --client-secret`, the CLI auto-targets the service account's organization. For the project: * If one project exists, it's auto-targeted * If multiple exist, you're prompted (or use `--project-id`) * If none exist, create one and target it manually **Via environment variables:** If using `PINECONE_CLIENT_ID` and `PINECONE_CLIENT_SECRET` without running `pc auth configure`, no target context is set automatically. Run `pc target` to set it. ```bash theme={null} # Change project (org is fixed to the service account's org) pc target -p "my-project" # Or select interactively pc target ``` ### API key When using an API key, control plane and data plane operations use the **key's org/project scope**, not the CLI's stored target context. The `pc target --show` output does not reflect what these operations actually use. API keys are scoped to a specific org and project and cannot access resources outside that scope. Admin API operations still use your user login or service account credentials (API keys can't authenticate Admin API calls). ## Managing target context ```bash theme={null} pc target --show # View current target pc target --clear # Clear target context ``` ### JSON mode and non-TTY environments Running `pc target --json` with no targeting flags returns the current target context as a JSON object. This is a local-state read — **no authentication is required**: ```bash theme={null} pc target --json ``` In non-TTY environments (CI/CD pipelines, shell pipes, scripts), JSON output is automatic — the same as passing `--json` explicitly. You do not need to add the flag in automation contexts. Use `--organization-id` and `--project-id` (instead of name flags) to set context reliably in scripts, since IDs are stable and unaffected by renames: ```bash theme={null} pc target --organization-id "org-abc123" --project-id "proj-xyz789" --json ``` # Pinecone SDKs overview Source: https://docs.pinecone.io/reference/pinecone-sdks Browse official Pinecone SDKs for Python, Node.js, Java, and Go, including the version mappings between SDK releases and API versions. ## Pinecone SDKs Official Pinecone SDKs provide convenient access to the [Pinecone APIs](/reference/api/introduction). ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and SDK versions are as follows: | | `2026-04` | `2025-10` | `2025-04` | `2025-01` | `2024-10` | `2024-07` | `2024-04` | | --------------------------------------------- | :---------- | :-------- | :-------- | :-------- | :-------- | :------------ | :-------- | | [Python SDK](/reference/sdks/python/overview) | v9.x | v8.x | v7.x | v6.x | v5.3.x | v5.0.x-v5.2.x | v4.x | | [Node.js SDK](/reference/sdks/node/overview) | v8.x | v7.x | v6.x | v5.x | v4.x | v3.x | v2.x | | [Java SDK](/reference/sdks/java/overview) | Coming soon | v6.x | v5.x | v4.x | v3.x | v2.x | v1.x | | [Go SDK](/reference/sdks/go/overview) | v6.x | v5.x | v4.x | v3.x | v2.x | v1.x | v0.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. The Java SDK targeting API version `2026-04` will be available soon. ## Limitations While Pinecone tracks read unit usage with decimal precision, the Pinecone API and SDKs round these values up to the nearest whole number in query, fetch, and list responses. For example, if a query uses 0.45 read units, the API and SDKs will report it as 1 read unit. For precise read unit reporting, see [index-level metrics](/guides/production/monitoring) or the organization-wide [Usage dashboard](/guides/manage-cost/monitor-usage-and-costs#monitor-organization-level-usage-and-costs). ## Community SDKs Find community-contributed SDKs for Pinecone. These libraries are not supported by Pinecone. * [Ruby SDK](https://github.com/ScotterC/pinecone) (contributed by [ScotterC](https://github.com/ScotterC)) * [Scala SDK](https://github.com/cequence-io/pinecone-scala) (contributed by [cequence-io](https://github.com/cequence-io)) * [PHP SDK](https://github.com/probots-io/pinecone-php) (contributed by [protobots-io](https://github.com/probots-io)) # Pinecone Go SDK Source: https://docs.pinecone.io/reference/sdks/go/overview Install and use the Pinecone Go SDK to manage indexes and namespaces, upsert vectors, run semantic search, and call the Admin and Inference APIs from Go. For installation instructions and usage examples, see the [Go SDK documentation](https://github.com/pinecone-io/go-pinecone). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/go-pinecone/issues). ## Requirements The Pinecone Go SDK requires a Go version with [modules](https://go.dev/wiki/Modules) support. ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and Go SDK versions are as follows: | API version | SDK version | | :---------- | :---------- | | `2026-04` | v6.x | | `2025-10` | v5.x | | `2025-04` | v4.x | | `2025-01` | v3.x | | `2024-10` | v2.x | | `2024-07` | v1.x | | `2024-04` | v0.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. ## Install To install the latest version of the [Go SDK](https://github.com/pinecone-io/go-pinecone), add a dependency to the current module: ```shell theme={null} go get github.com/pinecone-io/go-pinecone/v6/pinecone ``` To install a specific version of the Go SDK, run the following command: ```shell theme={null} go get github.com/pinecone-io/go-pinecone/v6/pinecone@ ``` To check your SDK version, run the following command: ```shell theme={null} go list -u -m all | grep go-pinecone ``` ## Upgrade Before upgrading to `v3.0.0` or later, update all relevant code to account for the breaking changes explained [here](/release-notes/2025#2025-02-07-4). Each major version carries its version number in the module path, so crossing a major requires updating the import path in every file that uses the SDK. For example, moving from `v4` to `v6` means changing: ```go theme={null} // before import "github.com/pinecone-io/go-pinecone/v4/pinecone" // after import "github.com/pinecone-io/go-pinecone/v6/pinecone" ``` Apart from the module path, `v5.0.0` and `v6.0.0` are backward compatible with the release lines before them. If you already have the Go SDK, upgrade to the latest version as follows: ```shell theme={null} go get -u github.com/pinecone-io/go-pinecone/v6/pinecone@latest ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance: ```Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) 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 manage organizations, projects, API keys, and [role-based access control](/guides/production/manage-rbac), initialize an `AdminClient` with [service account](/guides/organizations/manage-service-accounts) credentials instead: ```Go theme={null} package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } } ``` # Reference Source: https://docs.pinecone.io/reference/sdks/go/reference Reference documentation for the Pinecone Go SDK, including client setup, types, and methods for managing indexes and vector data operations. # OpenTelemetry support Source: https://docs.pinecone.io/reference/sdks/java/open-telemetry Monitor Pinecone Java SDK operations with OpenTelemetry metrics for client latency, server processing time, and errors via Prometheus. The Pinecone Java SDK provides built-in support for capturing per-operation response metadata, making it straightforward to monitor your Pinecone usage with [OpenTelemetry](https://opentelemetry.io/) or any other observability system. With this feature, you can track client-side latency, server processing time, network overhead, error rates, and more for every data plane operation your application makes. ## How it all fits together The SDK's observability support is designed to be flexible. You don't need to adopt the entire observability stack at once -- start simple and add layers as your needs grow. Here are the components involved and how they relate to each other: * **Pinecone Java SDK**: Exposes a `ResponseMetadataListener` callback, a plain Java interface with no external dependencies. At its simplest, you can log the metadata to the console. No additional tools required. * **[OpenTelemetry](https://opentelemetry.io/) (OTel)**: An open standard and SDK for producing structured telemetry data (metrics, traces, logs). If you want standardized metrics that follow [semantic conventions](https://opentelemetry.io/docs/specs/semconv/database/database-spans/), you add the OTel SDK and wire it to the listener. This is optional. * **OTel Collector**: A vendor-neutral service that receives telemetry from your app and forwards it to a storage backend. Optional -- many setups export directly from the app to a backend. * **Prometheus**: A time-series database that stores metrics, making them queryable over time. One popular storage option. * **Grafana**: A visualization and dashboarding tool that queries Prometheus (or other backends) and displays charts and alerts. One popular visualization option. A common setup chains these together: ``` Your App (OTel SDK) → OTel Collector → Prometheus (storage) → Grafana (visualization) ``` This is just one example pipeline. You can substitute Datadog, New Relic, or any OTel-compatible backend. You can also skip OTel entirely and use [Micrometer](#example-micrometerprometheus), custom logging, or any approach that suits your stack. ## Response metadata listener The Java SDK captures response metadata through a `ResponseMetadataListener` -- a functional interface you provide when building the Pinecone client. The listener is called after each data plane operation completes (whether it succeeds or fails), and receives a `ResponseMetadata` object containing timing, status, and context information. The SDK itself has no OpenTelemetry dependency. You bring your own observability library and decide what to do with the metadata. ### Supported operations The following data plane operations are instrumented, for both synchronous (`Index`) and asynchronous (`AsyncIndex`) usage: | Operation | Description | | --------- | -------------------------- | | `upsert` | Insert or update vectors | | `query` | Search for similar vectors | | `fetch` | Retrieve vectors by ID | | `update` | Update vector metadata | | `delete` | Delete vectors | ### Available metadata Each `ResponseMetadata` object provides the following fields: | Method | Description | OTel attribute | | ------------------------ | -------------------------------------------------- | ------------------------- | | `getOperationName()` | Operation type (e.g., `upsert`, `query`) | `db.operation.name` | | `getIndexName()` | Pinecone index name | `pinecone.index_name` | | `getNamespace()` | Namespace (empty string if default) | `db.namespace` | | `getServerAddress()` | Pinecone server host | `server.address` | | `getClientDurationMs()` | Total round-trip time in ms (always available) | -- | | `getServerDurationMs()` | Server processing time in ms (may be `null`) | -- | | `getNetworkOverheadMs()` | Client minus server duration in ms (may be `null`) | -- | | `getStatus()` | `"success"` or `"error"` | `status` | | `getGrpcStatusCode()` | Raw gRPC status code (e.g., `OK`, `UNAVAILABLE`) | `db.response.status_code` | | `getErrorType()` | Error category, or `null` if successful | `error.type` | Possible `errorType` values: `validation`, `connection`, `server`, `rate_limit`, `timeout`, `auth`, `not_found`, `unknown`. ### Recommended metrics If you're recording OTel metrics, the SDK example project uses these metric names, which follow [OTel semantic conventions for database clients](https://opentelemetry.io/docs/specs/semconv/database/database-spans/): | Metric | Type | Unit | Description | | ------------------------------------- | --------- | ---- | ------------------------------- | | `db.client.operation.duration` | Histogram | ms | Client-measured round-trip time | | `pinecone.server.processing.duration` | Histogram | ms | Server processing time | | `db.client.operation.count` | Counter | -- | Total number of operations | ## Quick start: Simple logging The simplest way to use the listener is to log the metadata directly. This requires no additional dependencies beyond the Pinecone SDK: ```java theme={null} import io.pinecone.clients.Pinecone; Pinecone client = new Pinecone.Builder("PINECONE_API_KEY") .withResponseMetadataListener(metadata -> { System.out.printf("Operation: %s | Client: %dms | Server: %sms | Network: %sms | Status: %s%n", metadata.getOperationName(), metadata.getClientDurationMs(), metadata.getServerDurationMs(), metadata.getNetworkOverheadMs(), metadata.getStatus()); }) .build(); ``` Once configured, every data plane operation automatically triggers the listener: ```java theme={null} Index index = client.getIndexConnection("my-index"); index.upsert("id-1", Arrays.asList(0.1f, 0.2f, 0.3f)); // Output: Operation: upsert | Client: 47ms | Server: 40ms | Network: 7ms | Status: success ``` ## Quick start: OpenTelemetry integration To record structured metrics with OpenTelemetry, add the OTel SDK dependencies and wire a metrics recorder to the listener. ### 1. Add dependencies Add the following to your `pom.xml`: ```xml theme={null} io.pinecone pinecone-client LATEST io.opentelemetry opentelemetry-sdk io.opentelemetry opentelemetry-sdk-metrics io.opentelemetry opentelemetry-exporter-otlp io.opentelemetry opentelemetry-bom 1.35.0 pom import ``` ### 2. Create a metrics recorder The SDK's [example project](https://github.com/pinecone-io/pinecone-java-client/tree/main/examples/java-otel-metrics) includes a reusable `PineconeMetricsRecorder` class you can copy into your project. It implements `ResponseMetadataListener` and records all three recommended metrics with proper OTel attributes: ```java theme={null} import io.opentelemetry.api.common.AttributeKey; import io.opentelemetry.api.common.Attributes; import io.opentelemetry.api.common.AttributesBuilder; import io.opentelemetry.api.metrics.LongCounter; import io.opentelemetry.api.metrics.LongHistogram; import io.opentelemetry.api.metrics.Meter; import io.pinecone.configs.ResponseMetadata; import io.pinecone.configs.ResponseMetadataListener; public class PineconeMetricsRecorder implements ResponseMetadataListener { private static final AttributeKey DB_SYSTEM = AttributeKey.stringKey("db.system"); private static final AttributeKey DB_OPERATION_NAME = AttributeKey.stringKey("db.operation.name"); private static final AttributeKey DB_NAMESPACE = AttributeKey.stringKey("db.namespace"); private static final AttributeKey PINECONE_INDEX_NAME = AttributeKey.stringKey("pinecone.index_name"); private static final AttributeKey SERVER_ADDRESS = AttributeKey.stringKey("server.address"); private static final AttributeKey STATUS = AttributeKey.stringKey("status"); private static final AttributeKey ERROR_TYPE = AttributeKey.stringKey("error.type"); private final LongHistogram clientDurationHistogram; private final LongHistogram serverDurationHistogram; private final LongCounter operationCounter; public PineconeMetricsRecorder(Meter meter) { this.clientDurationHistogram = meter.histogramBuilder("db.client.operation.duration") .setDescription("Duration of Pinecone operations from client perspective") .setUnit("ms") .ofLongs() .build(); this.serverDurationHistogram = meter.histogramBuilder("pinecone.server.processing.duration") .setDescription("Server processing time from x-pinecone-response-duration-ms header") .setUnit("ms") .ofLongs() .build(); this.operationCounter = meter.counterBuilder("db.client.operation.count") .setDescription("Total number of Pinecone operations") .setUnit("{operation}") .build(); } @Override public void onResponse(ResponseMetadata metadata) { AttributesBuilder attributesBuilder = Attributes.builder() .put(DB_SYSTEM, "pinecone") .put(DB_OPERATION_NAME, metadata.getOperationName()) .put(PINECONE_INDEX_NAME, metadata.getIndexName()) .put(SERVER_ADDRESS, metadata.getServerAddress()) .put(STATUS, metadata.getStatus()); String namespace = metadata.getNamespace(); if (namespace != null && !namespace.isEmpty()) { attributesBuilder.put(DB_NAMESPACE, namespace); } if (!metadata.isSuccess() && metadata.getErrorType() != null) { attributesBuilder.put(ERROR_TYPE, metadata.getErrorType()); } Attributes attributes = attributesBuilder.build(); clientDurationHistogram.record(metadata.getClientDurationMs(), attributes); Long serverDuration = metadata.getServerDurationMs(); if (serverDuration != null) { serverDurationHistogram.record(serverDuration, attributes); } operationCounter.add(1, attributes); } } ``` ### 3. Wire it into the Pinecone client Initialize the OTel SDK, create the recorder, and pass it to the Pinecone client builder: ```java theme={null} import io.opentelemetry.api.metrics.Meter; import io.opentelemetry.sdk.OpenTelemetrySdk; import io.opentelemetry.sdk.metrics.SdkMeterProvider; import io.opentelemetry.sdk.metrics.export.PeriodicMetricReader; import io.opentelemetry.exporter.otlp.metrics.OtlpGrpcMetricExporter; import io.pinecone.clients.Pinecone; // Set up OTel with OTLP exporter OtlpGrpcMetricExporter exporter = OtlpGrpcMetricExporter.builder() .setEndpoint("http://localhost:4317") .build(); SdkMeterProvider meterProvider = SdkMeterProvider.builder() .registerMetricReader(PeriodicMetricReader.builder(exporter).build()) .build(); OpenTelemetrySdk openTelemetry = OpenTelemetrySdk.builder() .setMeterProvider(meterProvider) .build(); // Create the metrics recorder Meter meter = openTelemetry.getMeter("pinecone.client"); PineconeMetricsRecorder recorder = new PineconeMetricsRecorder(meter); // Build the Pinecone client with the recorder Pinecone client = new Pinecone.Builder("PINECONE_API_KEY") .withResponseMetadataListener(recorder) .build(); // Use the client normally -- metrics are recorded automatically Index index = client.getIndexConnection("my-index"); index.upsert("id-1", Arrays.asList(0.1f, 0.2f, 0.3f)); index.query(3, Arrays.asList(0.1f, 0.2f, 0.3f)); ``` For a complete runnable example with Docker Compose, Prometheus, and Grafana, see the [java-otel-metrics example project](https://github.com/pinecone-io/pinecone-java-client/tree/main/examples/java-otel-metrics) in the SDK repository. ## Example: Micrometer/Prometheus If your application uses [Micrometer](https://micrometer.io/) (common in Spring Boot), you can wire the listener to Micrometer instead of the OTel SDK: ```java theme={null} import io.micrometer.core.instrument.MeterRegistry; import io.micrometer.core.instrument.Timer; import io.pinecone.clients.Pinecone; import java.util.concurrent.TimeUnit; Pinecone client = new Pinecone.Builder("PINECONE_API_KEY") .withResponseMetadataListener(metadata -> { Timer.builder("pinecone.client.duration") .tag("operation", metadata.getOperationName()) .tag("index", metadata.getIndexName()) .tag("status", metadata.getStatus()) .register(meterRegistry) .record(metadata.getClientDurationMs(), TimeUnit.MILLISECONDS); }) .build(); ``` ## Visualizing metrics Once your metrics are flowing to a backend, you can build dashboards to monitor your Pinecone operations. If you're using Prometheus and Grafana, here are some useful queries: **P50 and P95 client latency:** ```promql theme={null} histogram_quantile(0.5, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le)) histogram_quantile(0.95, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le)) ``` **P95 latency by operation type:** ```promql theme={null} histogram_quantile(0.95, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le, db_operation_name)) ``` **Operation count by type:** ```promql theme={null} sum by (db_operation_name) (db_client_operation_count_total) ``` ## Understanding the latency breakdown The `ResponseMetadata` object provides three timing values that help you pinpoint the source of latency issues: | Component | Method | What it measures | | ---------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | Client duration | `getClientDurationMs()` | Total round-trip time from request start to response completion. Always available. | | Server duration | `getServerDurationMs()` | Time the Pinecone backend spent processing the request. Extracted from the `x-pinecone-response-duration-ms` response header. May be `null`. | | Network overhead | `getNetworkOverheadMs()` | The difference: client duration minus server duration. Includes network latency, serialization, and deserialization. May be `null`. | Use these values to diagnose performance issues: * **High server duration**: The bottleneck is on the Pinecone backend. Consider optimizing your query (e.g., reducing `topK`, using metadata filters), or check the [Pinecone status page](https://status.pinecone.io/). * **High network overhead**: The bottleneck is in the network path between your application and Pinecone. Consider deploying your application closer to your index's cloud region, or check for network issues. ## Limitations * **Data plane operations only.** Control plane operations (e.g., creating or deleting indexes) are not currently instrumented. * **Bulk import operations** are not yet instrumented. * **Server duration may be unavailable.** The `getServerDurationMs()` method returns `null` if the `x-pinecone-response-duration-ms` header is not present in the response. * **Synchronous callback.** The listener is called synchronously after the gRPC response is received. Keep implementations lightweight and non-blocking to avoid adding latency to your operations. For heavy processing, queue the metadata for async handling. * **Exceptions are swallowed.** Exceptions thrown by the listener are logged but do not affect the operation result. ## Best practices * **Keep listeners lightweight.** Record metrics or enqueue work -- don't do I/O or heavy computation in the callback. * **Follow OTel semantic conventions.** Use the attribute names shown in the [recommended metrics](#recommended-metrics) table for interoperability with standard dashboards and tooling. * **Monitor both client and server duration.** Tracking both lets you separate Pinecone backend performance from network conditions. * **Set alerts on error rates.** Use the `status` and `error.type` attributes to build alerts for elevated error rates across operations. # Pinecone Java SDK Source: https://docs.pinecone.io/reference/sdks/java/overview Install and use the Pinecone Java SDK to manage indexes and namespaces, upsert vectors, run semantic search, and call the Admin and Inference APIs from Java. For installation instructions and usage examples, see the [Pinecone Java SDK documentation](https://github.com/pinecone-io/pinecone-java-client). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-java-client/issues). ## Requirements The Pinecone Java SDK requires Java 1.8 or later. ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and Java SDK versions are as follows: | API version | SDK version | | :---------- | :---------- | | `2025-04` | v5.x | | `2025-01` | v4.x | | `2024-10` | v3.x | | `2024-07` | v2.x | | `2024-04` | v1.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. ## Install To install the latest version of the [Java SDK](https://github.com/pinecone-io/pinecone-java-client), add a dependency to the current module: ```shell Java theme={null} # Maven io.pinecone pinecone-client 5.0.0 # Gradle implementation "io.pinecone:pinecone-client:5.0.0" ``` Alternatively, you can download the standalone uberjar [pinecone-client-4.0.0-all.jar](https://repo1.maven.org/maven2/io/pinecone/pinecone-client/4.0.0/pinecone-client-4.0.0-all.jar), which bundles the Pinecone SDK and all dependencies together. You can include this in your classpath like you do with any third-party JAR without having to obtain the `pinecone-client` dependencies separately. ## Upgrade Before upgrading to `v4.0.0`, update all relevant code to account for the breaking changes explained [here](/release-notes/2025#2025-02-07-3). If you are already using the Java SDK, upgrade the dependency in the current module to the latest version: ```shell Java theme={null} # Maven io.pinecone pinecone-client 5.0.0 # Gradle implementation "io.pinecone:pinecone-client:5.0.0" ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance: ```Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class InitializeClientExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); } } ``` ## Observability The Java SDK supports capturing per-operation response metadata for all data plane operations, including client-side latency, server processing time, network overhead, and error details. You can use this metadata with [OpenTelemetry](https://opentelemetry.io/), Micrometer, or any other observability system to monitor your Pinecone usage in production. For setup instructions and examples, see [OpenTelemetry support](/reference/sdks/java/open-telemetry). # Reference Source: https://docs.pinecone.io/reference/sdks/java/reference Reference documentation for the Pinecone Java SDK, including client setup, types, and methods for managing indexes and vector data operations. # Pinecone Node.js SDK Source: https://docs.pinecone.io/reference/sdks/node/overview Install and use the Pinecone Node.js and TypeScript SDK to manage indexes, upsert vectors, run semantic search, and call the Admin and Inference APIs. For installation instructions, usage examples, and reference information, see the [Pinecone Node.js SDK documentation](https://sdk.pinecone.io/typescript/). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-ts-client/issues). ## Requirements The Pinecone Node SDK requires TypeScript 4.1 or later and Node 18.x or later. ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and Node.js SDK versions are as follows: | API version | SDK version | | :---------- | :---------- | | `2026-04` | v8.x | | `2025-10` | v7.x | | `2025-04` | v6.x | | `2025-01` | v5.x | | `2024-10` | v4.x | | `2024-07` | v3.x | | `2024-04` | v2.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. ## Install To install the latest version of the [Node.js SDK](https://github.com/pinecone-io/pinecone-ts-client), written in TypeScript, run the following command: ```Shell theme={null} npm install @pinecone-database/pinecone ``` To check your SDK version, run the following command: ```Shell theme={null} npm list | grep @pinecone-database/pinecone ``` ## Upgrade If you already have the Node.js SDK, upgrade to the latest version as follows: ```Shell theme={null} npm install @pinecone-database/pinecone@latest ``` ## Initialize Once installed, you can import the library and then use an [API key](/guides/projects/manage-api-keys) to initialize a client instance: ```JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); ``` To manage organizations, projects, API keys, and [role-based access control](/guides/production/manage-rbac), initialize an `AdminClient` with [service account](/guides/organizations/manage-service-accounts) credentials instead. This requires v8.2.0 or later: ```JavaScript theme={null} import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); ``` You can also pass `clientId` and `clientSecret` directly to the constructor instead of setting environment variables. ## Proxy configuration If your network setup requires you to interact with Pinecone through a proxy, you can pass a custom `ProxyAgent` from the [`undici` library](https://undici.nodejs.org/#/). Below is an example of how to construct an `undici` `ProxyAgent` that routes network traffic through a [`mitm` proxy server](https://mitmproxy.org/) while hitting Pinecone's `/indexes` endpoint. The following strategy relies on Node's native [`fetch`](https://nodejs.org/docs/latest/api/globals.html#fetch) implementation, released in Node v16 and stabilized in Node v21. If you are running Node versions 18-21, you may experience issues stemming from the instability of the feature. There are currently no known issues related to proxying in Node v18+. ```JavaScript JavaScript theme={null} import { Pinecone, type PineconeConfiguration, } from '@pinecone-database/pinecone'; import { Dispatcher, ProxyAgent } from 'undici'; import * as fs from 'fs'; const cert = fs.readFileSync('path/to/mitmproxy-ca-cert.pem'); const client = new ProxyAgent({ uri: 'https://your-proxy.com', requestTls: { port: 'YOUR_PROXY_SERVER_PORT', ca: cert, host: 'YOUR_PROXY_SERVER_HOST', }, }); const customFetch = ( input: string | URL | Request, init: RequestInit | undefined ) => { return fetch(input, { ...init, dispatcher: client as Dispatcher, keepalive: true, # optional }); }; const config: PineconeConfiguration = { apiKey: 'YOUR_API_KEY', fetchApi: customFetch, }; const pc = new Pinecone(config); const indexes = async () => { return await pc.listIndexes(); }; indexes().then((response) => { console.log('My indexes: ', response); }); ``` # Reference Source: https://docs.pinecone.io/reference/sdks/node/reference Reference documentation for the Pinecone Node.js SDK, including client setup, types, and methods for managing indexes and vector data operations. # Pinecone Python SDK Source: https://docs.pinecone.io/reference/sdks/python/overview Install and use the Pinecone SDK for Pinecone Python SDK: auth, typed clients, and API operations. For installation instructions, usage examples, and. For installation instructions, usage examples, and reference information, see the [Pinecone Python SDK documentation](https://sdk.pinecone.io/python/). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-python-client/issues). The Pinecone Python SDK is distributed on PyPI using the package name `pinecone`. By default, the `pinecone` package has a minimal set of dependencies and interacts with Pinecone via HTTP requests. However, you can install the following extras to unlock additional functionality: * `pinecone[grpc]` adds dependencies on `grpcio` and related libraries needed to run data operations such as upserts and queries over [gRPC](https://grpc.io/) for a modest performance improvement. * `pinecone[asyncio]` adds a dependency on `aiohttp` and enables usage of `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). For more details, see [Async requests](#async-requests). ## Requirements The Pinecone Python SDK requires Python 3.9 or later. It has been tested with CPython versions from 3.9 to 3.13. ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and Python SDK versions are as follows: | API version | SDK version | | :---------- | :------------ | | `2025-04` | v7.x | | `2025-01` | v6.x | | `2024-10` | v5.3.x | | `2024-07` | v5.0.x-v5.2.x | | `2024-04` | v4.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. ## Install To install the latest version of the [Python SDK](https://github.com/pinecone-io/pinecone-python-client), run the following command: ```shell theme={null} # Install the latest version pip install pinecone # Install the latest version with gRPC extras pip install "pinecone[grpc]" # Install the latest version with asyncio extras pip install "pinecone[asyncio]" ``` To install a specific version of the Python SDK, run the following command: ```shell pip theme={null} # Install a specific version pip install pinecone== # Install a specific version with gRPC extras pip install "pinecone[grpc]"== # Install a specific version with asyncio extras pip install "pinecone[asyncio]"== ``` To check your SDK version, run the following command: ```shell pip theme={null} pip show pinecone ``` To use the [Inference API](/reference/api/introduction#inference), you must be on version 5.0.0 or later. ### Install the Pinecone Assistant Python plugin As of Python SDK v7.0.0, the `pinecone-plugin-assistant` package is included by default. It is only necessary to install the package if you are using a version of the Python SDK prior to v7.0.0. ```shell HTTP theme={null} pip install --upgrade pinecone pinecone-plugin-assistant ``` ## Upgrade Before upgrading to `v6.0.0`, update all relevant code to account for the breaking changes explained [here](https://github.com/pinecone-io/pinecone-python-client/blob/main/docs/upgrading.md). Also, make sure to upgrade using the `pinecone` package name instead of `pinecone-client`; upgrading with the latter will not work as of `v6.0.0`. If you already have the Python SDK, upgrade to the latest version as follows: ```shell theme={null} # Upgrade to the latest version pip install pinecone --upgrade # Upgrade to the latest version with gRPC extras pip install "pinecone[grpc]" --upgrade # Upgrade to the latest version with asyncio extras pip install "pinecone[asyncio]" --upgrade ``` ## Initialize Once installed, you can import the library and then use an [API key](/guides/projects/manage-api-keys) to initialize a client instance: ```Python HTTP theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` ```python gRPC theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` When [creating an index](/guides/index-data/create-an-index), import the `ServerlessSpec` or `PodSpec` class as well: ```Python Serverless index theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ) ) ``` ```Python Pod-based index theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import PodSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=PodSpec( environment="us-west-1-gcp", pod_type="p1.x1", pods=1 ) ) ``` ## Proxy configuration If your network setup requires you to interact with Pinecone through a proxy, you will need to pass additional configuration using optional keyword parameters: * `proxy_url`: The location of your proxy. This could be an HTTP or HTTPS URL depending on your proxy setup. * `proxy_headers`: Accepts a python dictionary which can be used to pass any custom headers required by your proxy. If your proxy is protected by authentication, use this parameter to pass basic authentication headers with a digest of your username and password. The `make_headers` utility from `urllib3` can be used to help construct the dictionary. **Note:** Not supported with Asyncio. * `ssl_ca_certs`: By default, the client will perform SSL certificate verification using the CA bundle maintained by Mozilla in the [`certifi`](https://pypi.org/project/certifi/) package. If your proxy is using self-signed certicates, use this parameter to specify the path to the certificate (PEM format). * `ssl_verify`: SSL verification is enabled by default, but it is disabled when set to `False`. It is not recommened to go into production with SSL verification disabled. ```python HTTP theme={null} from pinecone import Pinecone import urllib3 from urllib3.util import make_headers pc = Pinecone( api_key="YOUR_API_KEY", proxy_url='https://your-proxy.com', proxy_headers=make_headers(proxy_basic_auth='username:password'), ssl_ca_certs='path/to/cert-bundle.pem' ) ``` ```python gRPC theme={null} from pinecone.grpc import PineconeGRPC as Pinecone import urllib3 from urllib3.util import make_headers pc = Pinecone( api_key="YOUR_API_KEY", proxy_url='https://your-proxy.com', proxy_headers=make_headers(proxy_basic_auth='username:password'), ssl_ca_certs='path/to/cert-bundle.pem' ) ``` ```python asyncio theme={null} import asyncio from pinecone import PineconeAsyncio async def main(): async with PineconeAsyncio( api_key="YOUR_API_KEY", proxy_url='https://your-proxy.com', ssl_ca_certs='path/to/cert-bundle.pem' ) as pc: # Do async things await pc.list_indexes() asyncio.run(main()) ``` ## Async requests Pinecone Python SDK versions 6.0.0 and later provide `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). Asyncio support makes it possible to use Pinecone with modern async web frameworks such as [FastAPI](https://fastapi.tiangolo.com/), [Quart](https://quart.palletsprojects.com/en/latest/), and [Sanic](https://sanic.dev/en/), and should significantly increase the efficiency of running requests in parallel. Use the [`PineconeAsyncio`](https://sdk.pinecone.io/python/asyncio.html) class to create and manage indexes and the [`IndexAsyncio`](https://sdk.pinecone.io/python/asyncio.html#pinecone.db_data.IndexAsyncio) class to read and write index data. To ensure that sessions are properly closed, use the `async with` syntax when creating `PineconeAsyncio` and `IndexAsyncio` objects. ```python Manage indexes theme={null} # pip install "pinecone[asyncio]" import asyncio from pinecone import PineconeAsyncio, ServerlessSpec async def main(): async with PineconeAsyncio(api_key="YOUR_API_KEY") as pc: if not await pc.has_index(index_name): desc = await pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ), deletion_protection="disabled", tags={ "environment": "development" } ) asyncio.run(main()) ``` ```python Read and write index data theme={null} # pip install "pinecone[asyncio]" import asyncio from pinecone import Pinecone async def main(): pc = Pinecone(api_key="YOUR_API_KEY") async with pc.IndexAsyncio(host="INDEX_HOST") as idx: await idx.upsert_records( namespace="example-namespace", records=[ { "id": "1", "title": "The Great Gatsby", "author": "F. Scott Fitzgerald", "description": "The story of the mysteriously wealthy Jay Gatsby and his love for the beautiful Daisy Buchanan.", "year": 1925, }, { "id": "2", "title": "To Kill a Mockingbird", "author": "Harper Lee", "description": "A young girl comes of age in the segregated American South and witnesses her father's courageous defense of an innocent black man.", "year": 1960, }, { "id": "3", "title": "1984", "author": "George Orwell", "description": "In a dystopian future, a totalitarian regime exercises absolute control through pervasive surveillance and propaganda.", "year": 1949, }, ] ) asyncio.run(main()) ``` ## Query across namespaces Each query is limited to a single [namespace](/guides/index-data/indexing-overview#namespaces). However, the Pinecone Python SDK provides a `query_namespaces` utility method to run a query in parallel across multiple namespaces in an index and then merge the result sets into a single ranked result set with the `top_k` most relevant results. The `query_namespaces` method accepts most of the same arguments as `query` with the addition of a required `namespaces` parameter. When using the Python SDK without gRPC extras, to get good performance, it is important to set values for the `pool_threads` and `connection_pool_maxsize` properties on the index client. The `pool_threads` setting is the number of threads available to execute requests, while `connection_pool_maxsize` is the number of cached http connections that will be held. Since these tasks are not computationally heavy and are mainly i/o bound, it should be okay to have a high ratio of threads to cpus. The combined results include the sum of all read unit usage used to perform the underlying queries for each namespace. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index( name="docs-example", pool_threads=50, # <-- make sure to set these connection_pool_maxsize=50, # <-- make sure to set these ) query_vec = [ 0.1, ...] # an embedding vector with same dimension as the index combined_results = index.query_namespaces( vector=query_vec, namespaces=['ns1', 'ns2', 'ns3', 'ns4'], metric="cosine", top_k=10, include_values=False, include_metadata=True, filter={"genre": { "$eq": "comedy" }}, show_progress=False, ) for scored_vec in combined_results.matches: print(scored_vec) print(combined_results.usage) ``` When using the Python SDK with gRPC extras, there is no need to set the `connection_pool_maxsize` because grpc makes efficient use of open connections by default. ```python Python theme={null} from pinecone.grpc import PineconeGRPC pc = PineconeGRPC(api_key="YOUR_API_KEY") index = pc.Index( name="docs-example", pool_threads=50, # <-- make sure to set this ) query_vec = [ 0.1, ...] # an embedding vector with same dimension as the index combined_results = index.query_namespaces( vector=query_vec, namespaces=['ns1', 'ns2', 'ns3', 'ns4'], metric="cosine", top_k=10, include_values=False, include_metadata=True, filter={"genre": { "$eq": "comedy" }}, show_progress=False, ) for scored_vec in combined_results.matches: print(scored_vec) print(combined_results.usage) ``` ## Upsert from a dataframe To quickly ingest data when using the [Python SDK](/reference/sdks/python/overview), use the `upsert_from_dataframe` method. The method includes retry logic and`batch_size`, and is performant especially with Parquet file data sets. The following example upserts the `uora_all-MiniLM-L6-bm25` dataset as a dataframe. ```Python Python theme={null} from pinecone import Pinecone, ServerlessSpec from pinecone_datasets import list_datasets, load_dataset pc = Pinecone(api_key="API_KEY") dataset = load_dataset("quora_all-MiniLM-L6-bm25") pc.create_index( name="docs-example", dimension=384, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ) ) # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.upsert_from_dataframe(dataset.drop(columns=["blob"])) ``` # Reference Source: https://docs.pinecone.io/reference/sdks/python/reference Reference documentation for the Pinecone Python SDK, including client setup, types, and methods for managing indexes and vector data operations. # Spark-Pinecone connector Source: https://docs.pinecone.io/reference/tools/pinecone-spark-connector Pinecone data tools: Use the connector to efficiently create, ingest, and update vector embeddings at scale with Databricks and Pinecone. Use the [`spark-pinecone` connector](https://github.com/pinecone-io/spark-pinecone/) to efficiently create, ingest, and update [vector embeddings](https://www.pinecone.io/learn/vector-embeddings/) at scale with [Databricks and Pinecone](/integrations/databricks). ## Install the Spark-Pinecone connector 1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster). 2. Configure the library as follows: 1. Select **File path/S3** as the **Library Source**. 2. Enter the S3 URI for the Pinecone assembly JAR file: ``` s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar ``` Databricks platform users must use the Pinecone assembly jar listed above to ensure that the proper dependecies are installed. 3. Click **Install**. 1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster). 2. Configure the library as follows: 1. Select **File path/S3** as the **Library Source**. 2. Enter the S3 URI for the Pinecone assembly JAR file: ``` s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar ``` 3. Click **Install**. 1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster). 2. Configure the library as follows: 1. [Download the Pinecone assembly JAR file](https://repo1.maven.org/maven2/io/pinecone/spark-pinecone_2.12/1.1.0/). 2. Select **Workspace** as the **Library Source**. 3. Upload the JAR file. 4. Click **Install**. ## Batch upsert To batch upsert embeddings to Pinecone: ```python Python theme={null} from pyspark import SparkConf from pyspark.sql import SparkSession from pyspark.sql.types import StructType, StructField, ArrayType, FloatType, StringType, LongType # Your API key and index name api_key = "PINECONE_API_KEY" index_name = "PINECONE_INDEX_NAME" source_tag = "PINECONE_SOURCE_TAG" COMMON_SCHEMA = StructType([ StructField("id", StringType(), False), StructField("namespace", StringType(), True), StructField("values", ArrayType(FloatType(), False), False), StructField("metadata", StringType(), True), StructField("sparse_values", StructType([ StructField("indices", ArrayType(LongType(), False), False), StructField("values", ArrayType(FloatType(), False), False) ]), True) ]) # Initialize Spark spark = SparkSession.builder.getOrCreate() # Read the file and apply the schema df = spark.read \ .option("multiLine", value = True) \ .option("mode", "PERMISSIVE") \ .schema(COMMON_SCHEMA) \ .json("src/test/resources/sample.jsonl") # Show if the read was successful df.show() # Write the dataFrame to Pinecone in batches df.write \ .option("pinecone.apiKey", api_key) \ .option("pinecone.indexName", index_name) \ .option("pinecone.sourceTag", source_tag) \ .format("io.pinecone.spark.pinecone.Pinecone") \ .mode("append") \ .save() ``` ```scala Scala theme={null} import io.pinecone.spark.pinecone.{COMMON_SCHEMA, PineconeOptions} import org.apache.spark.SparkConf import org.apache.spark.sql.{SaveMode, SparkSession} object MainApp extends App { // Your API key and index name val apiKey = "PINECONE_API_KEY" val indexName = "PINECONE_INDEX_NAME" val sourceTag = "PINECONE_SOURCE_TAG" // Configure Spark to run locally with all available cores val conf = new SparkConf() .setMaster("local[*]") // Create a Spark session with the defined configuration val spark = SparkSession.builder().config(conf).getOrCreate() // Read the JSON file into a DataFrame, applying the COMMON_SCHEMA val df = spark.read .option("multiLine", value = true) .option("mode", "PERMISSIVE") .schema(COMMON_SCHEMA) .json("src/test/resources/sample.jsonl") // path to sample.jsonl // Define Pinecone options as a Map val pineconeOptions = Map( PineconeOptions.PINECONE_API_KEY_CONF -> apiKey, PineconeOptions.PINECONE_INDEX_NAME_CONF -> indexName, PineconeOptions.PINECONE_SOURCE_TAG_CONF -> sourceTag ) // Show if the read was successful df.show(df.count().toInt) // Write the DataFrame to Pinecone using the defined options in batches df.write .options(pineconeOptions) .format("io.pinecone.spark.pinecone.Pinecone") .mode(SaveMode.Append) .save() } ``` For a guide on how to set up batch upserts, refer to the [Databricks integration page](/integrations/databricks#setup-guide). ## Stream upsert To stream upsert embeddings to Pinecone: ```python Python theme={null} from pyspark.sql import SparkSession from pyspark.sql.types import StructType, StructField, ArrayType, FloatType, StringType, LongType import os # Your API key and index name api_key = "PINECONE_API_KEY" index_name = "PINECONE_INDEX_NAME" source_tag = "PINECONE_SOURCE_TAG" COMMON_SCHEMA = StructType([ StructField("id", StringType(), False), StructField("namespace", StringType(), True), StructField("values", ArrayType(FloatType(), False), False), StructField("metadata", StringType(), True), StructField("sparse_values", StructType([ StructField("indices", ArrayType(LongType(), False), False), StructField("values", ArrayType(FloatType(), False), False) ]), True) ]) # Initialize Spark session spark = SparkSession.builder \ .appName("StreamUpsertExample") \ .config("spark.sql.shuffle.partitions", 3) \ .master("local") \ .getOrCreate() # Read the stream of JSON files, applying the schema from the input directory lines = spark.readStream \ .option("multiLine", True) \ .option("mode", "PERMISSIVE") \ .schema(COMMON_SCHEMA) \ .json("path/to/input/directory/") # Write the stream to Pinecone using the defined options upsert = lines.writeStream \ .format("io.pinecone.spark.pinecone.Pinecone") \ .option("pinecone.apiKey", api_key) \ .option("pinecone.indexName", index_name) \ .option("pinecone.sourceTag", source_tag) \ .option("checkpointLocation", "path/to/checkpoint/dir") \ .outputMode("append") \ .start() upsert.awaitTermination() ``` ```scala Scala theme={null} import io.pinecone.spark.pinecone.{COMMON_SCHEMA, PineconeOptions} import org.apache.spark.SparkConf import org.apache.spark.sql.{SaveMode, SparkSession} object MainApp extends App { // Your API key and index name val apiKey = "PINECONE_API_KEY" val indexName = "PINECONE_INDEX_NAME" // Create a Spark session val spark = SparkSession.builder() .appName("StreamUpsertExample") .config("spark.sql.shuffle.partitions", 3) .master("local") .getOrCreate() // Read the JSON files into a DataFrame, applying the COMMON_SCHEMA from input directory val lines = spark.readStream .option("multiLine", value = true) .option("mode", "PERMISSIVE") .schema(COMMON_SCHEMA) .json("path/to/input/directory/") // Define Pinecone options as a Map val pineconeOptions = Map( PineconeOptions.PINECONE_API_KEY_CONF -> System.getenv("PINECONE_API_KEY"), PineconeOptions.PINECONE_INDEX_NAME_CONF -> System.getenv("PINECONE_INDEX"), PineconeOptions.PINECONE_SOURCE_TAG_CONF -> System.getenv("PINECONE_SOURCE_TAG") ) // Write the stream to Pinecone using the defined options val upsert = lines .writeStream .format("io.pinecone.spark.pinecone.Pinecone") .options(pineconeOptions) .option("checkpointLocation", "path/to/checkpoint/dir") .outputMode("append") .start() upsert.awaitTermination() } ``` ## Learn more * [Spark-Pinecone connector setup guide](/integrations/databricks#setup-guide) * [GitHub](https://github.com/pinecone-io/spark-pinecone) # Create an API key Source: https://docs.pinecone.io/reference/api/2026-04/admin/create_api_key https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/projects/{project_id}/api-keys Create an API key for a project to authenticate Data Plane and Control Plane requests. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const apiKey = await admin.apiKeys.create('YOUR_PROJECT_ID', { name: 'Example API Key', roles: ['ProjectEditor'], }); // `apiKey.value` is returned only at creation time and cannot be retrieved // later. Store it securely and never log it. console.log(apiKey.key); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } roles := []string{"ProjectEditor"} apiKey, err := adminClient.APIKey.Create(ctx, "YOUR_PROJECT_ID", &pinecone.CreateAPIKeyParams{ Name: "Example API Key", Roles: &roles, }) if err != nil { log.Fatalf("Failed to create API key: %v", err) } // Value is returned only at creation time — store it securely and never log it fmt.Printf("Successfully created API key: %v\n", apiKey.Key.Id) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later resource "pinecone_api_key" "example" { name = "Example API Key" project_id = "YOUR_PROJECT_ID" roles = ["ProjectEditor"] } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_PROJECT_ID="YOUR_PROJECT_ID" curl "https://api.pinecone.io/admin/projects/$PINECONE_PROJECT_ID/api-keys" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -d '{ "name": "Example API Key", "roles": ["ProjectEditor"] }' ``` ```json curl theme={null} { "key": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Example API key", "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "roles": [ "ProjectEditor" ] }, "value": "string" } ``` # Invite a user to the organization Source: https://docs.pinecone.io/reference/api/2026-04/admin/create_invite https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/invites Invite a user to the organization by email and grant their initial role bindings. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const invite = await admin.invites.create({ email: 'newhire@example.com', roleBindings: [ { resourceType: 'organization', role: 'OrgMember' }, { resourceType: 'project', resourceId: 'a2f7dddb-1597-4eff-9f71-535fde243f58', role: 'ProjectMember', }, ], }); console.log(invite); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } projectId := "a2f7dddb-1597-4eff-9f71-535fde243f58" invite, err := adminClient.Invite.Create(ctx, &pinecone.CreateInviteParams{ Email: "newhire@example.com", RoleBindings: []pinecone.RoleBindingInput{ {ResourceType: pinecone.ResourceTypeOrganization, Role: "OrgMember"}, {ResourceType: pinecone.ResourceTypeProject, ResourceId: &projectId, Role: "ProjectMember"}, }, }) if err != nil { log.Fatalf("Failed to create invite: %v", err) } fmt.Printf("Invited %v (status: %v)\n", invite.Email, invite.Status) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later resource "pinecone_invite" "newhire" { email = "newhire@example.com" role_bindings = [ { resource_type = "organization" role = "OrgMember" }, { resource_type = "project" resource_id = "a2f7dddb-1597-4eff-9f71-535fde243f58" role = "ProjectMember" } ] } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl "https://api.pinecone.io/admin/invites" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -d '{ "email": "newhire@example.com", "role_bindings": [ { "resource_type": "organization", "role": "OrgMember" }, { "resource_type": "project", "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58", "role": "ProjectMember" } ] }' ``` ```json curl theme={null} { "id": "9c8e3528-b9c0-4358-84ce-84c28e91b566", "email": "newhire@example.com", "status": "pending", "expires_at": "2026-05-21T03:00:00Z", "processed_at": null, "created_at": "2026-04-14T20:00:00Z" } ``` # Create a new project Source: https://docs.pinecone.io/reference/api/2026-04/admin/create_project https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/projects Create a new project. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const project = await admin.projects.create({ name: 'example-project' }); console.log(project); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } project, err := adminClient.Project.Create(ctx, &pinecone.CreateProjectParams{ Name: "example-project", }) if err != nil { log.Fatalf("Failed to create project: %v", err) } fmt.Printf("Successfully created project: %v\n", project.Id) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later resource "pinecone_project" "example" { name = "example-project" } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl "https://api.pinecone.io/admin/projects" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -d '{ "name":"example-project" }' ``` ```json curl theme={null} { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "example-project", "max_pods": 0, "force_encryption_with_cmek": false, "organization_id": "string", "created_at": "2025-03-16T22:46:45.030Z" } ``` # Create a role binding Source: https://docs.pinecone.io/reference/api/2026-04/admin/create_role_binding https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/role-bindings Grant a role to a principal at an organization or project scope. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const roleBinding = await admin.roleBindings.create({ principalType: 'service_account', principalId: 'f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c', resourceType: 'project', resourceId: 'a2f7dddb-1597-4eff-9f71-535fde243f58', role: 'DataPlaneEditor', }); console.log(roleBinding); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } projectId := "a2f7dddb-1597-4eff-9f71-535fde243f58" roleBinding, err := adminClient.RoleBinding.Create(ctx, &pinecone.CreateRoleBindingParams{ PrincipalType: pinecone.PrincipalTypeServiceAccount, PrincipalId: "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c", ResourceType: pinecone.ResourceTypeProject, ResourceId: &projectId, Role: "DataPlaneEditor", }) if err != nil { log.Fatalf("Failed to create role binding: %v", err) } fmt.Printf("Successfully created role binding: %v\n", roleBinding.Id) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # Bindings are immutable; changing any attribute forces replacement resource "pinecone_role_binding" "ci_data_plane_editor" { principal_type = "service_account" principal_id = "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c" resource_type = "project" resource_id = "a2f7dddb-1597-4eff-9f71-535fde243f58" role = "DataPlaneEditor" } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl "https://api.pinecone.io/admin/role-bindings" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -d '{ "principal_type": "service_account", "principal_id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c", "resource_type": "project", "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58", "role": "DataPlaneEditor" }' ``` ```json curl theme={null} { "id": "9a8e3528-b9c0-4358-84ce-84c28e91b566", "principal_type": "service_account", "principal_id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c", "resource_type": "project", "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58", "role": "DataPlaneEditor", "created_at": "2026-04-10T15:23:00Z" } ``` # Create a service account Source: https://docs.pinecone.io/reference/api/2026-04/admin/create_service_account https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/service-accounts Create a service account with optional initial role bindings; the client secret is returned only once. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); // `clientSecret` is returned only once and cannot be retrieved later const { serviceAccount, clientSecret } = await admin.serviceAccounts.create({ name: 'ci-prod', roleBindings: [ { resourceType: 'project', resourceId: 'a2f7dddb-1597-4eff-9f71-535fde243f58', role: 'DataPlaneEditor', }, ], }); console.log(serviceAccount); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } projectId := "a2f7dddb-1597-4eff-9f71-535fde243f58" sa, err := adminClient.ServiceAccount.Create(ctx, &pinecone.CreateServiceAccountParams{ Name: "ci-prod", RoleBindings: []pinecone.RoleBindingInput{ { ResourceType: pinecone.ResourceTypeProject, ResourceId: &projectId, Role: "DataPlaneEditor", }, }, }) if err != nil { log.Fatalf("Failed to create service account: %v", err) } // ClientSecret is returned only once — store it securely and never log it fmt.Printf("Successfully created service account: %v\n", sa.ServiceAccount.Id) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # Roles are assigned with separate pinecone_role_binding resources resource "pinecone_service_account" "ci_prod" { name = "ci-prod" } resource "pinecone_role_binding" "ci_prod_data_plane_editor" { principal_id = pinecone_service_account.ci_prod.id principal_type = "service_account" resource_type = "project" resource_id = "a2f7dddb-1597-4eff-9f71-535fde243f58" role = "DataPlaneEditor" } output "ci_prod_client_secret" { value = pinecone_service_account.ci_prod.client_secret sensitive = true } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl "https://api.pinecone.io/admin/service-accounts" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -d '{ "name": "ci-prod", "role_bindings": [ { "resource_type": "project", "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58", "role": "DataPlaneEditor" } ] }' ``` ```json curl theme={null} { "service_account": { "id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c", "name": "ci-prod", "client_id": "l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn", "created_at": "2026-04-10T15:23:00Z", "updated_at": "2026-04-10T15:23:00Z" }, "client_secret": "8p-kkC23XOWvkCosKq-BOn3G74qp__rBcDMxc82iB4gfzRvuhSCRBKM7C5Q7TAzj" } ``` # Delete an API key Source: https://docs.pinecone.io/reference/api/2026-04/admin/delete_api_key https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/api-keys/{api_key_id} Delete an API key from a project. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); await admin.apiKeys.delete('YOUR_API_KEY_ID'); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } if err := adminClient.APIKey.Delete(ctx, "YOUR_API_KEY_ID"); err != nil { log.Fatalf("Failed to delete API key: %v", err) } } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # This block defines the API key. To delete it, either remove the block and run # `terraform apply`, or run: # terraform destroy -target=pinecone_api_key.example resource "pinecone_api_key" "example" { name = "Example API Key" project_id = "YOUR_PROJECT_ID" } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_API_KEY_ID="YOUR_KEY_ID" curl -X DELETE "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" ``` # Delete an invite Source: https://docs.pinecone.io/reference/api/2026-04/admin/delete_invite https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/invites/{invite_id} Delete a pending or expired invite and its role bindings; to remove an accepted user, delete the user instead. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); await admin.invites.delete('YOUR_INVITE_ID'); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } if err := adminClient.Invite.Delete(ctx, "YOUR_INVITE_ID"); err != nil { log.Fatalf("Failed to delete invite: %v", err) } } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # This block defines the invite. To revoke a pending invite, either remove the # block and run `terraform apply`, or run: # terraform destroy -target=pinecone_invite.newhire resource "pinecone_invite" "newhire" { email = "newhire@example.com" role_bindings = [ { resource_type = "organization" role = "OrgMember" } ] } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_INVITE_ID="YOUR_INVITE_ID" curl -X DELETE "https://api.pinecone.io/admin/invites/$PINECONE_INVITE_ID" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" ``` # Delete a project Source: https://docs.pinecone.io/reference/api/2026-04/admin/delete_project https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/projects/{project_id} Delete a project and all its configuration; delete its indexes, assistants, backups, and collections first. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); await admin.projects.delete('YOUR_PROJECT_ID'); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } if err := adminClient.Project.Delete(ctx, "YOUR_PROJECT_ID"); err != nil { log.Fatalf("Failed to delete project: %v", err) } } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # This block defines the project. To delete it, either remove the block and run # `terraform apply`, or run: # terraform destroy -target=pinecone_project.example resource "pinecone_project" "example" { name = "example-project" } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PROJECT_ID="YOUR_PROJECT_ID" curl -X DELETE "https://api.pinecone.io/admin/projects/$PROJECT_ID" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" ``` # Delete a role binding Source: https://docs.pinecone.io/reference/api/2026-04/admin/delete_role_binding https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/role-bindings/{role_binding_id} Delete a role binding; permissions are revoked when the deletion completes. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); await admin.roleBindings.delete('YOUR_ROLE_BINDING_ID'); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } if err := adminClient.RoleBinding.Delete(ctx, "YOUR_ROLE_BINDING_ID"); err != nil { log.Fatalf("Failed to delete role binding: %v", err) } } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # This block defines the role binding. To revoke the role, either remove the # block and run `terraform apply`, or run: # terraform destroy -target=pinecone_role_binding.ci_data_plane_editor resource "pinecone_role_binding" "ci_data_plane_editor" { principal_type = "service_account" principal_id = "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c" resource_type = "project" resource_id = "a2f7dddb-1597-4eff-9f71-535fde243f58" role = "DataPlaneEditor" } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_ROLE_BINDING_ID="YOUR_ROLE_BINDING_ID" curl -X DELETE "https://api.pinecone.io/admin/role-bindings/$PINECONE_ROLE_BINDING_ID" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" ``` # Delete a service account Source: https://docs.pinecone.io/reference/api/2026-04/admin/delete_service_account https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/service-accounts/{service_account_id} Delete a service account and its role bindings; tokens it minted are revoked within a few seconds. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); await admin.serviceAccounts.delete('YOUR_SERVICE_ACCOUNT_ID'); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } if err := adminClient.ServiceAccount.Delete(ctx, "YOUR_SERVICE_ACCOUNT_ID"); err != nil { log.Fatalf("Failed to delete service account: %v", err) } } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # This block defines the service account. To delete it, either remove the block # and run `terraform apply`, or run: # terraform destroy -target=pinecone_service_account.ci_prod resource "pinecone_service_account" "ci_prod" { name = "ci-prod" } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_SERVICE_ACCOUNT_ID="YOUR_SERVICE_ACCOUNT_ID" curl -X DELETE "https://api.pinecone.io/admin/service-accounts/$PINECONE_SERVICE_ACCOUNT_ID" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" ``` # Remove a user from the organization Source: https://docs.pinecone.io/reference/api/2026-04/admin/delete_user https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml delete /admin/users/{user_id} Remove a user from the organization and revoke their role bindings; their Pinecone account is not deleted. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); await admin.users.delete('YOUR_USER_ID'); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } if err := adminClient.User.Delete(ctx, "YOUR_USER_ID"); err != nil { log.Fatalf("Failed to delete user: %v", err) } } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # Users join by accepting an invite, so import the existing member first: # terraform import pinecone_user.teammate YOUR_USER_ID # Then remove the resource block and run `terraform apply` to remove them # from the organization. resource "pinecone_user" "teammate" { id = "YOUR_USER_ID" } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_USER_ID="YOUR_USER_ID" curl -X DELETE "https://api.pinecone.io/admin/users/$PINECONE_USER_ID" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" ``` # Get API key details Source: https://docs.pinecone.io/reference/api/2026-04/admin/fetch_api_key https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/api-keys/{api_key_id} Get an API key's details, excluding its secret. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const apiKey = await admin.apiKeys.describe('YOUR_API_KEY_ID'); console.log(apiKey); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } apiKey, err := adminClient.APIKey.Describe(ctx, "YOUR_API_KEY_ID") if err != nil { log.Fatalf("Failed to describe API key: %v", err) } fmt.Printf("API key: %v (%v)\n", apiKey.Name, apiKey.Id) } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_API_KEY_ID="3fa85f64-5717-4562-b3fc-2c963f66afa6" curl -X GET "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "accept: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "roles": [ "ProjectEditor" ] } ``` # Get invite details Source: https://docs.pinecone.io/reference/api/2026-04/admin/fetch_invite https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/invites/{invite_id} Get an invite in the caller's organization by ID. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const invite = await admin.invites.describe('YOUR_INVITE_ID'); console.log(invite); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } invite, err := adminClient.Invite.Describe(ctx, "YOUR_INVITE_ID") if err != nil { log.Fatalf("Failed to describe invite: %v", err) } fmt.Printf("Invite: %v (status: %v)\n", invite.Email, invite.Status) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later data "pinecone_invite" "example" { id = "YOUR_INVITE_ID" } output "invite_status" { value = data.pinecone_invite.example.status } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_INVITE_ID="9c8e3528-b9c0-4358-84ce-84c28e91b566" curl -X GET "https://api.pinecone.io/admin/invites/$PINECONE_INVITE_ID" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "accept: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "id": "9c8e3528-b9c0-4358-84ce-84c28e91b566", "email": "newhire@example.com", "status": "pending", "expires_at": "2026-05-21T03:00:00Z", "processed_at": null, "created_at": "2026-04-14T20:00:00Z" } ``` # Get project details Source: https://docs.pinecone.io/reference/api/2026-04/admin/fetch_project https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/projects/{project_id} Get a project's details. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const project = await admin.projects.describe('YOUR_PROJECT_ID'); console.log(project); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } project, err := adminClient.Project.Describe(ctx, "YOUR_PROJECT_ID") if err != nil { log.Fatalf("Failed to describe project: %v", err) } fmt.Printf("Project: %v (%v)\n", project.Name, project.Id) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later data "pinecone_project" "example" { id = "YOUR_PROJECT_ID" } output "project_name" { value = data.pinecone_project.example.name } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PROJECT_ID="3fa85f64-5717-4562-b3fc-2c963f66afa6" curl -X GET "https://api.pinecone.io/admin/projects/$PROJECT_ID" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "accept: application/json" ``` ```json curl theme={null} { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "example-project", "max_pods": 0, "force_encryption_with_cmek": false, "organization_id": "string", "created_at": "2025-03-17T00:30:23.262Z" } ``` # Get role binding details Source: https://docs.pinecone.io/reference/api/2026-04/admin/fetch_role_binding https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/role-bindings/{role_binding_id} Get a role binding in the caller's organization by ID. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const roleBinding = await admin.roleBindings.describe('YOUR_ROLE_BINDING_ID'); console.log(roleBinding); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } roleBinding, err := adminClient.RoleBinding.Describe(ctx, "YOUR_ROLE_BINDING_ID") if err != nil { log.Fatalf("Failed to describe role binding: %v", err) } fmt.Printf("Role binding: %v (%v)\n", roleBinding.Role, roleBinding.Id) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later data "pinecone_role_binding" "example" { id = "YOUR_ROLE_BINDING_ID" } output "role" { value = data.pinecone_role_binding.example.role } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_ROLE_BINDING_ID="9a8e3528-b9c0-4358-84ce-84c28e91b566" curl -X GET "https://api.pinecone.io/admin/role-bindings/$PINECONE_ROLE_BINDING_ID" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "accept: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "id": "9a8e3528-b9c0-4358-84ce-84c28e91b566", "principal_type": "service_account", "principal_id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c", "resource_type": "project", "resource_id": "a2f7dddb-1597-4eff-9f71-535fde243f58", "role": "DataPlaneEditor", "created_at": "2026-04-10T15:23:00Z" } ``` # Get service account details Source: https://docs.pinecone.io/reference/api/2026-04/admin/fetch_service_account https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/service-accounts/{service_account_id} Get a service account by ID; the client secret is returned only from create and rotate-secret requests. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const serviceAccount = await admin.serviceAccounts.describe('YOUR_SERVICE_ACCOUNT_ID'); console.log(serviceAccount); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } sa, err := adminClient.ServiceAccount.Describe(ctx, "YOUR_SERVICE_ACCOUNT_ID") if err != nil { log.Fatalf("Failed to describe service account: %v", err) } fmt.Printf("Service account: %v (%v)\n", sa.Name, sa.Id) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later data "pinecone_service_account" "example" { id = "YOUR_SERVICE_ACCOUNT_ID" } output "service_account_name" { value = data.pinecone_service_account.example.name } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_SERVICE_ACCOUNT_ID="f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c" curl -X GET "https://api.pinecone.io/admin/service-accounts/$PINECONE_SERVICE_ACCOUNT_ID" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "accept: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c", "name": "My Service Account", "client_id": "l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn", "created_at": "2026-04-10T15:23:00Z", "updated_at": "2026-04-12T09:11:00Z" } ``` # Get user details Source: https://docs.pinecone.io/reference/api/2026-04/admin/fetch_user https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/users/{user_id} Get a user in the caller's organization by ID. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const user = await admin.users.describe('YOUR_USER_ID'); console.log(user); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } user, err := adminClient.User.Describe(ctx, "YOUR_USER_ID") if err != nil { log.Fatalf("Failed to describe user: %v", err) } fmt.Printf("User: %v (%v)\n", user.Email, user.Id) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # Look up a user by id or by email data "pinecone_user" "example" { id = "YOUR_USER_ID" } output "user_name" { value = data.pinecone_user.example.name } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_USER_ID="e2e92523-85dc-4142-b8c2-e681be8b78df" curl -X GET "https://api.pinecone.io/admin/users/$PINECONE_USER_ID" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "accept: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "id": "e2e92523-85dc-4142-b8c2-e681be8b78df", "email": "alice@example.com", "name": "Alice Example", "created_at": "2026-04-10T15:23:00Z", "updated_at": "2026-04-12T09:11:00Z" } ``` # Create an access token Source: https://docs.pinecone.io/reference/api/2026-04/admin/get_token https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/oauth_2026-04.oas.yaml post /oauth/token Obtain an access token for a service account using the OAuth2 client credentials flow. An access token is needed to authorize requests to the Pinecone Admin API. The host domain for OAuth endpoints is `login.pinecone.io`. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // You don't call this endpoint directly when using the SDK. The AdminClient // exchanges your service account credentials for an access token on the first // admin request and reuses it for subsequent calls. const admin = new AdminClient({ clientId: 'YOUR_CLIENT_ID', clientSecret: 'YOUR_CLIENT_SECRET', }); const { data: projects } = await admin.projects.list(); console.log(projects); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() // You don't call this endpoint directly when using the SDK. The AdminClient // exchanges your service account credentials for an access token. adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: "YOUR_CLIENT_ID", ClientSecret: "YOUR_CLIENT_SECRET", }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } projects, err := adminClient.Project.List(ctx) if err != nil { log.Fatalf("Failed to list projects: %v", err) } fmt.Printf("Found %v projects\n", len(projects)) } ``` ```bash curl theme={null} curl "https://login.pinecone.io/oauth/token" \ # Note: Base URL is login.pinecone.io -H "X-Pinecone-Api-Version: 2026-04" \ -H "Content-Type: application/json" \ -d '{ "grant_type": "client_credentials", "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "audience": "https://api.pinecone.io/" }' ``` ```json curl theme={null} { "access_token":"YOUR_ACCESS_TOKEN", "expires_in":86400, "token_type":"Bearer" } ``` # List API keys Source: https://docs.pinecone.io/reference/api/2026-04/admin/list_api_keys https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/projects/{project_id}/api-keys List all API keys in a project. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const { data: apiKeys } = await admin.apiKeys.list('YOUR_PROJECT_ID'); console.log(apiKeys); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } apiKeys, err := adminClient.APIKey.List(ctx, "YOUR_PROJECT_ID") if err != nil { log.Fatalf("Failed to list API keys: %v", err) } for _, apiKey := range apiKeys { fmt.Printf("API key: %v (%v)\n", apiKey.Name, apiKey.Id) } } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_PROJECT_ID="YOUR_PROJECT_ID" curl -X GET "https://api.pinecone.io/admin/projects/$PINECONE_PROJECT_ID/api-keys" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "data": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "roles": [ "ProjectEditor" ] } ] } ``` # List invites Source: https://docs.pinecone.io/reference/api/2026-04/admin/list_invites https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/invites List pending and expired invites in the caller's organization. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const { data: invites } = await admin.invites.list(); console.log(invites); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } invites, err := adminClient.Invite.List(ctx, &pinecone.ListInvitesParams{}) if err != nil { log.Fatalf("Failed to list invites: %v", err) } for _, invite := range invites.Data { fmt.Printf("Invite: %v (status: %v)\n", invite.Email, invite.Status) } } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later data "pinecone_invites" "all" {} output "invite_emails" { value = [for invite in data.pinecone_invites.all.invites : invite.email] } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl -X GET "https://api.pinecone.io/admin/invites" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "accept: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "data": [ { "id": "9c8e3528-b9c0-4358-84ce-84c28e91b566", "email": "newhire@example.com", "status": "pending", "expires_at": "2026-05-21T03:00:00Z", "processed_at": null, "created_at": "2026-04-14T20:00:00Z" } ], "pagination": { "next": "eyJsYXN0X2lkIjoiOWM4ZTM1MjgifQ==" } } ``` # List projects Source: https://docs.pinecone.io/reference/api/2026-04/admin/list_projects https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/projects List all projects in an organization. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const { data: projects } = await admin.projects.list(); console.log(projects); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } projects, err := adminClient.Project.List(ctx) if err != nil { log.Fatalf("Failed to list projects: %v", err) } for _, project := range projects { fmt.Printf("Project: %v (%v)\n", project.Name, project.Id) } } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later data "pinecone_projects" "all" {} output "project_names" { value = [for project in data.pinecone_projects.all.projects : project.name] } ``` ```bash curl theme={null} curl -X GET "https://api.pinecone.io/admin/projects" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "data": [ { "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "name": "example-project", "max_pods": 0, "force_encryption_with_cmek": true, "organization_id": "", "created_at": "2023-11-07T05:31:56Z" } ] } ``` # List role bindings Source: https://docs.pinecone.io/reference/api/2026-04/admin/list_role_bindings https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/role-bindings List role bindings in the caller's organization, optionally filtered by principal, resource, and role. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const { data: roleBindings } = await admin.roleBindings.list({ principalType: 'user', principalId: 'e2e92523-85dc-4142-b8c2-e681be8b78df', }); console.log(roleBindings); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } principalType := pinecone.PrincipalTypeUser principalId := "e2e92523-85dc-4142-b8c2-e681be8b78df" roleBindings, err := adminClient.RoleBinding.List(ctx, &pinecone.ListRoleBindingsParams{ PrincipalType: &principalType, PrincipalId: &principalId, }) if err != nil { log.Fatalf("Failed to list role bindings: %v", err) } for _, roleBinding := range roleBindings.Data { fmt.Printf("Role binding: %v (%v)\n", roleBinding.Role, roleBinding.Id) } } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later data "pinecone_role_bindings" "user_roles" { principal_type = "user" principal_id = "e2e92523-85dc-4142-b8c2-e681be8b78df" } output "user_roles" { value = [for b in data.pinecone_role_bindings.user_roles.role_bindings : b.role] } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl -X GET "https://api.pinecone.io/admin/role-bindings?principal_type=user&principal_id=e2e92523-85dc-4142-b8c2-e681be8b78df" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "accept: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "data": [ { "id": "5a86ed21-daf1-448d-a9ca-f92a0fd839d3", "principal_type": "user", "principal_id": "e2e92523-85dc-4142-b8c2-e681be8b78df", "resource_type": "organization", "resource_id": "-ExampleOrgId0000000", "role": "OrgMember", "created_at": "2026-04-10T15:23:00Z" } ], "pagination": { "next": "eyJsYXN0X2lkIjoiNWE4NmVkMjEifQ==" } } ``` # List service accounts Source: https://docs.pinecone.io/reference/api/2026-04/admin/list_service_accounts https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/service-accounts List service accounts in the caller's organization. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const { data: serviceAccounts } = await admin.serviceAccounts.list(); console.log(serviceAccounts); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } serviceAccounts, err := adminClient.ServiceAccount.List(ctx, &pinecone.ListServiceAccountsParams{}) if err != nil { log.Fatalf("Failed to list service accounts: %v", err) } for _, sa := range serviceAccounts.Data { fmt.Printf("Service account: %v (%v)\n", sa.Name, sa.Id) } } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later data "pinecone_service_accounts" "all" {} output "service_account_names" { value = [for sa in data.pinecone_service_accounts.all.service_accounts : sa.name] } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl -X GET "https://api.pinecone.io/admin/service-accounts" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "accept: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "data": [ { "id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c", "name": "My Service Account", "client_id": "l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn", "created_at": "2026-04-10T15:23:00Z", "updated_at": "2026-04-12T09:11:00Z" } ], "pagination": { "next": "eyJsYXN0X2lkIjoiZDI0MTc3YTAifQ==" } } ``` # List users in the organization Source: https://docs.pinecone.io/reference/api/2026-04/admin/list_users https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml get /admin/users List users in the caller's organization, optionally filtered by email address. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const { data: users } = await admin.users.list(); console.log(users); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } users, err := adminClient.User.List(ctx, &pinecone.ListUsersParams{}) if err != nil { log.Fatalf("Failed to list users: %v", err) } for _, user := range users.Data { fmt.Printf("User: %v (%v)\n", user.Email, user.Id) } } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later data "pinecone_users" "all" {} output "user_emails" { value = [for user in data.pinecone_users.all.users : user.email] } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl -X GET "https://api.pinecone.io/admin/users" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "accept: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "data": [ { "id": "e2e92523-85dc-4142-b8c2-e681be8b78df", "email": "alice@example.com", "name": "Alice Example", "created_at": "2026-04-10T15:23:00Z", "updated_at": "2026-04-12T09:11:00Z" } ], "pagination": { "next": "eyJsYXN0X2lkIjoiZTJlOTI1MjMifQ==" } } ``` # Resend an invite email Source: https://docs.pinecone.io/reference/api/2026-04/admin/resend_invite https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/invites/{invite_id}/resend Resend the invite email and extend its expiration to 7 days from now; limited to 100 emails per hour per organization. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const invite = await admin.invites.resend('YOUR_INVITE_ID'); console.log(invite); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } invite, err := adminClient.Invite.Resend(ctx, "YOUR_INVITE_ID") if err != nil { log.Fatalf("Failed to resend invite: %v", err) } fmt.Printf("Resent invite to %v (status: %v)\n", invite.Email, invite.Status) } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_INVITE_ID="9c8e3528-b9c0-4358-84ce-84c28e91b566" curl -X POST "https://api.pinecone.io/admin/invites/$PINECONE_INVITE_ID/resend" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" ``` ```json curl theme={null} { "id": "9c8e3528-b9c0-4358-84ce-84c28e91b566", "email": "newhire@example.com", "status": "pending", "expires_at": "2026-05-28T20:14:00Z", "processed_at": null, "created_at": "2026-04-14T20:00:00Z" } ``` # Rotate a service account's OAuth client secret Source: https://docs.pinecone.io/reference/api/2026-04/admin/rotate_service_account_secret https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml post /admin/service-accounts/{service_account_id}/rotate-secret Rotate a service account's OAuth client secret; the previous secret and its tokens are revoked within seconds and the new secret is returned only once. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); // The previous secret is invalidated, and the new one is returned only once const { serviceAccount, clientSecret } = await admin.serviceAccounts.rotateSecret( 'YOUR_SERVICE_ACCOUNT_ID' ); console.log(serviceAccount); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } sa, err := adminClient.ServiceAccount.RotateSecret(ctx, "YOUR_SERVICE_ACCOUNT_ID") if err != nil { log.Fatalf("Failed to rotate service account secret: %v", err) } // ClientSecret is returned only once — store it securely and never log it fmt.Printf("Successfully rotated secret for service account: %v\n", sa.ServiceAccount.Id) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # Change rotate_trigger to any new value to issue and store a new secret resource "pinecone_service_account" "ci_prod" { name = "ci-prod" rotate_trigger = "2026-04-10" } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_SERVICE_ACCOUNT_ID="f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c" curl -X POST "https://api.pinecone.io/admin/service-accounts/$PINECONE_SERVICE_ACCOUNT_ID/rotate-secret" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" ``` ```json curl theme={null} { "service_account": { "id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c", "name": "My Service Account", "client_id": "l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn", "created_at": "2026-04-10T15:23:00Z", "updated_at": "2026-04-10T15:23:00Z" }, "client_secret": "8p-kkC23XOWvkCosKq-BOn3G74qp__rBcDMxc82iB4gfzRvuhSCRBKM7C5Q7TAzj" } ``` # Update an API key Source: https://docs.pinecone.io/reference/api/2026-04/admin/update_api_key https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml patch /admin/api-keys/{api_key_id} Update an API key's name and roles. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const apiKey = await admin.apiKeys.update('YOUR_API_KEY_ID', { name: 'New API key name', roles: ['ProjectEditor'], }); console.log(apiKey); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } name := "New API key name" roles := []string{"ProjectEditor"} apiKey, err := adminClient.APIKey.Update(ctx, "YOUR_API_KEY_ID", &pinecone.UpdateAPIKeyParams{ Name: &name, Roles: &roles, }) if err != nil { log.Fatalf("Failed to update API key: %v", err) } fmt.Printf("Successfully updated API key: %v\n", apiKey.Name) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # Change the name or roles on an existing resource, then run `terraform apply` resource "pinecone_api_key" "example" { name = "New API key name" project_id = "YOUR_PROJECT_ID" roles = ["ProjectEditor"] } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_API_KEY_ID="YOUR_API_KEY_ID" curl -X PATCH "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -d '{ "name": "New API key name", "roles": ["ProjectEditor"] }' ``` ```json curl theme={null} { "key": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "New API key name", "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "roles": [ "ProjectEditor" ] }, "value": "string" } ``` # Update a project Source: https://docs.pinecone.io/reference/api/2026-04/admin/update_project https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml patch /admin/projects/{project_id} Update a project's name, maximum number of Pods, or customer-managed encryption key (CMEK). ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const project = await admin.projects.update('YOUR_PROJECT_ID', { name: 'updated-example-project', }); console.log(project); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } name := "updated-example-project" project, err := adminClient.Project.Update(ctx, "YOUR_PROJECT_ID", &pinecone.UpdateProjectParams{ Name: &name, }) if err != nil { log.Fatalf("Failed to update project: %v", err) } fmt.Printf("Successfully updated project: %v\n", project.Name) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # Change the name on an existing resource, then run `terraform apply` resource "pinecone_project" "example" { name = "updated-example-project" } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PROJECT_ID="YOUR_PROJECT_ID" curl -X PATCH "https://api.pinecone.io/admin/projects/$PROJECT_ID" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" \ -d '{ "name": "updated-example-project" }' ``` ```json curl theme={null} { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "updated-example-project", "max_pods": 0, "force_encryption_with_cmek": false, "organization_id": "string", "created_at": "2025-03-17T00:42:31.912Z" } ``` # Update a service account Source: https://docs.pinecone.io/reference/api/2026-04/admin/update_service_account https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/admin_2026-04.oas.yaml patch /admin/service-accounts/{service_account_id} Update a service account's name; role bindings are managed through the role-binding endpoints. ```javascript JavaScript theme={null} // Requires Node.js SDK v8.2.0 or later import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); const serviceAccount = await admin.serviceAccounts.update('YOUR_SERVICE_ACCOUNT_ID', { name: 'ci-prod-renamed', }); console.log(serviceAccount); ``` ```go Go theme={null} // Requires Go SDK v6.0.0 or later package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } name := "ci-prod-renamed" sa, err := adminClient.ServiceAccount.Update(ctx, "YOUR_SERVICE_ACCOUNT_ID", &pinecone.UpdateServiceAccountParams{ Name: &name, }) if err != nil { log.Fatalf("Failed to update service account: %v", err) } fmt.Printf("Successfully updated service account: %v\n", sa.Name) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v4.0.0 or later # Change the name on an existing resource, then run `terraform apply` resource "pinecone_service_account" "ci_prod" { name = "ci-prod-renamed" } ``` ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_SERVICE_ACCOUNT_ID="YOUR_SERVICE_ACCOUNT_ID" curl -X PATCH "https://api.pinecone.io/admin/service-accounts/$PINECONE_SERVICE_ACCOUNT_ID" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -d '{ "name": "ci-prod-renamed" }' ``` ```json curl theme={null} { "id": "f8a3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c", "name": "ci-prod-renamed", "client_id": "l3Ow0CmFyc4jOONcwiKUCRqQKN0tiCAn", "created_at": "2026-04-10T15:23:00Z", "updated_at": "2026-04-12T09:11:00Z" } ``` # Create a backup of an index Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/create_backup https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml post /indexes/{index_name}/backups Create a backup of an index. ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="docs-example" curl "https://api.pinecone.io/indexes/$INDEX_NAME/backups" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2026-04" \ -d '{ "name": "example-backup", "description": "Monthly backup of production index" }' ``` ```json curl theme={null} { "backup_id":"8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "source_index_id":"f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "source_index_name":"docs-example", "tags":{}, "name":"example-backup", "description":"Monthly backup of production index", "status":"Ready", "cloud":"aws", "region":"us-east-1", "dimension":1024, "record_count":96, "namespace_count":3, "size_bytes":1069169, "created_at":"2025-05-14T16:37:25.625540Z" } ``` # Create backup schedule Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/create_backup_schedule POST https://api.pinecone.io/indexes/{index_name}/backup-schedules Create a recurring backup schedule for a Pinecone serverless index using the API, including daily, weekly, or monthly frequency and retention policy. This endpoint requires `X-Pinecone-API-Version: unstable`. Create a recurring backup schedule for an index. Backups are created automatically based on the specified frequency and expired according to the retention policy. Each index supports one active schedule at a time. ### Path parameters The name of the index to create a backup schedule for. ### Body parameters A human-readable name for the backup schedule. Backups created by the schedule are automatically named `{name}-{ISO8601_timestamp}`. The schedule configuration. The type of schedule. Currently only `time-based` is supported. How often backups are created. One of `daily`, `weekly`, or `monthly`. The retention policy for backups created by this schedule. The number of days after which backups created by this schedule are automatically deleted. ### Error responses | Status | Description | | :----- | :----------------------------------------------------------------------------- | | 403 | Scheduled backups are not available for your plan. | | 404 | Index not found. | | 409 | This index already has an enabled backup schedule. Disable or delete it first. | ```bash curl theme={null} curl -sS -X POST "https://api.pinecone.io/indexes/${INDEX_NAME}/backup-schedules" \ -H "api-key: ${PINECONE_API_KEY}" \ -H "X-Pinecone-API-Version: unstable" \ -H "Content-Type: application/json" \ -d '{ "name": "my-nightly-backup", "schedule": { "type": "time-based", "frequency": "daily" }, "retention": { "expire_after_days": 7 } }' ``` ```json curl theme={null} { "schedule_id": "c688ed12-5a39-4254-9518-bd394b7f4886", "name": "my-nightly-backup", "index_id": "d40265e4-a492-402b-9cf1-973b4908b7a0", "project_id": "cc95c601-bf08-4973-9a1d-a65a1b528759", "schedule_type": "time-based", "frequency": "daily", "retention_expire_after_days": 7, "enabled": true, "next_scheduled_run": "2026-04-24T06:00:00+00:00", "created_at": "2026-04-23T16:36:51.267528+00:00" } ``` # Create a collection Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/create_collection https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml post /collections Create a Pinecone collection. Serverless indexes do not support collections. ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s "https://api.pinecone.io/collections" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" \ -d '{ "name": "example-collection", "source": "docs-example" }' ``` ```json curl theme={null} { "name": "example-collection", "status": "Initializing", "environment": "us-east-1-aws", "dimension": 1536 } ``` # Create an index from a backup Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/create_index_from_backup https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml post /backups/{backup_id}/create-index Create an index from a backup. For serverless backups, you can optionally set `read_capacity` so the restored index is created with dedicated read nodes (DRN) instead of defaulting to on-demand capacity. ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" BACKUP_ID="a65ff585-d987-4da5-a622-72e19a6ed5f4" curl "https://api.pinecone.io/backups/$BACKUP_ID/create-index" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H 'Content-Type: application/json' \ -d '{ "name": "restored-index", "tags": { "tag0": "val0", "tag1": "val1" }, "deletion_protection": "enabled" }' ``` ```json curl theme={null} { "restore_job_id":"e9ba8ff8-7948-4cfa-ba43-34227f6d30d4", "index_id":"025117b3-e683-423c-b2d1-6d30fbe5027f" } ``` # Delete a backup Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/delete_backup https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml delete /backups/{backup_id} Delete a backup. ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" BACKUP_ID="9947520e-d5a1-4418-a78d-9f464c9969da" curl -X DELETE "https://api.pinecone.io/backups/$BACKUP_ID" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" ``` # Delete backup schedule Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/delete_backup_schedule DELETE https://api.pinecone.io/backup-schedules/{schedule_id} Delete a backup schedule for a Pinecone serverless index using the API by schedule ID, while preserving all previously created backup snapshots. This endpoint requires `X-Pinecone-API-Version: unstable`. Delete a backup schedule. This does **not** delete any backups that were previously created by the schedule. ### Path parameters The ID of the backup schedule to delete. ```bash curl theme={null} curl -sS -o /dev/null -w "%{http_code}\n" -X DELETE \ "https://api.pinecone.io/backup-schedules/${SCHEDULE_ID}" \ -H "api-key: ${PINECONE_API_KEY}" \ -H "X-Pinecone-API-Version: unstable" ``` ```text curl theme={null} 204 ``` # Delete a collection Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/delete_collection https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml delete /collections/{collection_name} Delete an existing collection. Serverless indexes do not support collections. ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X DELETE "https://api.pinecone.io/collections/example-collection" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" ``` # Describe a backup Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/describe_backup https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml get /backups/{backup_id} Get a description of a backup. ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" BACKUP_ID="8c85e612-ed1c-4f97-9f8c-8194e07bcf71" curl -X GET "https://api.pinecone.io/backups/$BACKUP_ID" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "accept: application/json" ``` ```json curl theme={null} { "backup_id":"8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "source_index_id":"f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "source_index_name":"docs-example", "tags":{}, "name":"example-backup", "description":"Monthly backup of production index", "status":"Ready", "cloud":"aws", "region":"us-east-1", "dimension":1024, "record_count":98, "namespace_count":3, "size_bytes":1069169, "created_at":"2025-03-11T18:29:50.549505Z" } ``` # Describe backup schedule Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/describe_backup_schedule GET https://api.pinecone.io/backup-schedules/{schedule_id} Retrieve details for a Pinecone backup schedule by schedule ID, including frequency, retention days, next scheduled run, and enabled status. This endpoint requires `X-Pinecone-API-Version: unstable`. Get the details of a specific backup schedule by its ID. ### Path parameters The ID of the backup schedule. ```bash curl theme={null} curl -sS "https://api.pinecone.io/backup-schedules/${SCHEDULE_ID}" \ -H "api-key: ${PINECONE_API_KEY}" \ -H "X-Pinecone-API-Version: unstable" ``` ```json curl theme={null} { "schedule_id": "c688ed12-5a39-4254-9518-bd394b7f4886", "name": "my-nightly-backup", "index_id": "d40265e4-a492-402b-9cf1-973b4908b7a0", "project_id": "cc95c601-bf08-4973-9a1d-a65a1b528759", "schedule_type": "time-based", "frequency": "daily", "retention_expire_after_days": 7, "enabled": true, "next_scheduled_run": "2026-04-24T06:00:00+00:00", "created_at": "2026-04-23T16:36:51.267528+00:00" } ``` # Describe a collection Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/describe_collection https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml get /collections/{collection_name} Get a description of a collection. Serverless indexes do not support collections. ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/collections/tiny-collection" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "name": "example-collection", "status": "Ready", "environment": "us-east-1-aws", "size": 3075398, "vector_count": 99, "dimension": 1536 } ``` # Describe a restore job Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/describe_restore_job https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml get /restore-jobs/{job_id} Get a description of a restore job. ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" JOB_ID="9857add2-99d4-4399-870e-aa7f15d8d326" curl "https://api.pinecone.io/restore-jobs/$JOB_ID" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'accept: application/json' ``` ```json curl theme={null} { "restore_job_id": "9857add2-99d4-4399-870e-aa7f15d8d326", "backup_id": "94a63aeb-efae-4f7a-b059-75d32c27ca57", "target_index_name": "restored-index", "target_index_id": "0d8aed24-adf8-4b77-8e10-fd674309dc85", "status": "Completed", "created_at": "2025-04-25T18:14:05.227526Z", "completed_at": "2025-04-25T18:14:11.074618Z", "percent_complete": 100 } ``` # List backup schedule history Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/list_backup_schedule_history GET https://api.pinecone.io/backup-schedules/{schedule_id}/history List execution history for a Pinecone backup schedule, including scheduled runs, completed backups, statuses, and cursor-based pagination support. This endpoint requires `X-Pinecone-API-Version: unstable`. List backups created by a specific schedule. When a backup's `status` is `Scheduled`, the `scheduled_execution_at` field indicates the planned run time. Supports pagination. ### Path parameters The ID of the backup schedule. ### Query parameters The maximum number of results to return. A token for fetching the next page of results. ```bash curl theme={null} curl -sS "https://api.pinecone.io/backup-schedules/${SCHEDULE_ID}/history" \ -H "api-key: ${PINECONE_API_KEY}" \ -H "X-Pinecone-API-Version: unstable" ``` ```json curl theme={null} { "data": [ { "backup_id": "16098c2f-f9ff-4db3-b8b2-4b02d119cd53", "source_index_id": "d40265e4-a492-402b-9cf1-973b4908b7a0", "source_index_name": "my-index", "tags": {}, "name": "my-nightly-backup-20260424T060000Z", "description": null, "status": "Scheduled", "scheduled_execution_at": "2026-04-24T06:00:00.244035Z", "cloud": "aws", "region": "us-east-1", "dimension": 2, "schema": null, "record_count": null, "namespace_count": null, "size_bytes": null, "created_at": "2026-04-23T16:36:51.511526Z" } ], "pagination": null } ``` # List backup schedules Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/list_backup_schedules GET https://api.pinecone.io/indexes/{index_name}/backup-schedules List all backup schedules configured for a Pinecone serverless index, including schedule IDs, frequency, retention, and next scheduled run times. This endpoint requires `X-Pinecone-API-Version: unstable`. List all backup schedules configured for a specific index. ### Path parameters The name of the index to list backup schedules for. ```bash curl theme={null} curl -sS "https://api.pinecone.io/indexes/${INDEX_NAME}/backup-schedules" \ -H "api-key: ${PINECONE_API_KEY}" \ -H "X-Pinecone-API-Version: unstable" ``` ```json curl theme={null} { "data": [ { "schedule_id": "c688ed12-5a39-4254-9518-bd394b7f4886", "name": "my-nightly-backup", "index_id": "d40265e4-a492-402b-9cf1-973b4908b7a0", "project_id": "cc95c601-bf08-4973-9a1d-a65a1b528759", "schedule_type": "time-based", "frequency": "daily", "retention_expire_after_days": 7, "enabled": true, "next_scheduled_run": "2026-04-24T06:00:00+00:00", "created_at": "2026-04-23T16:36:51.267528+00:00" } ], "pagination": null } ``` # List collections Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/list_collections https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml get /collections List all collections in a project. Serverless indexes do not support collections. ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/collections" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "collections": [ { "name": "example-collection1", "status": "Ready", "environment": "us-east-1-aws", "size": 3081918, "vector_count": 99, "dimension": 3 }, { "name": "example-collection1", "status": "Ready", "environment": "us-east-1-aws", "size": 160087040000000, "vector_count": 10000000, "dimension": 1536 } ] } ``` # List backups for an index Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/list_index_backups https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml get /indexes/{index_name}/backups When `include_deleted` is false (or omitted), `index_name` must resolve to an active index in the project. If no active index by that name exists—including the case where only deleted indexes have used the name—the API returns **404**, not an empty list. When `include_deleted` is true, the API returns backups from every index in the project that has ever used this name (active and deleted). The `source_index_deleted_at` field is present only when the backup is from a deleted index. **404** is returned only when no index by that name has ever existed in the project (active or deleted). ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="docs-example" curl -X GET "https://api.pinecone.io/indexes/$INDEX_NAME/backups" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "accept: application/json" ``` ```json curl theme={null} { "data": [ { "backup_id":"9947520e-d5a1-4418-a78d-9f464c9969da", "source_index_id":"8433941a-dae7-43b5-ac2c-d3dab4a56b2b", "source_index_name":"docs-example", "tags":{}, "name":"example-backup", "description":"Monthly backup of production index", "status":"Pending", "cloud":"aws", "region":"us-east-1", "dimension":1024, "record_count":98, "namespace_count":3, "size_bytes":1069169, "created_at":"2025-03-11T18:29:50.549505Z" } ], "pagination":null } ``` # List backups for all indexes in a project Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/list_project_backups https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml get /backups List all backups for a project. ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -X GET "https://api.pinecone.io/backups" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "accept: application/json" ``` ```json curl theme={null} { "data": [ { "backup_id": "e12269b0-a29b-4af0-9729-c7771dec03e3", "source_index_id": "bcb5b3c9-903e-4cb6-8b37-a6072aeb874f", "source_index_name": "docs-example", "tags": null, "name": "example-backup", "description": null, "status": "Ready", "cloud": "aws", "region": "us-east-1", "dimension": 0, "record_count": 96, "namespace_count": 1, "size_bytes": 86393, "created_at": "2025-05-14T17:00:45.803146Z" }, { "backup_id": "d686451d-1ede-4004-9f72-7d22cc799b6e", "source_index_id": "b49f27d1-1bf3-49c6-82b5-4ae46f00f0e6", "source_index_name": "docs-example2", "tags": null, "name": "example-backup2", "description": null, "status": "Ready", "cloud": "aws", "region": "us-east-1", "dimension": 1024, "record_count": 50, "namespace_count": 1, "size_bytes": 545171, "created_at": "2025-05-14T17:00:34.814371Z" }, { "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "source_index_name": "docs-example3", "tags": {}, "name": "example-backup3", "description": "Monthly backup of production index", "status": "Ready", "cloud": "aws", "region": "us-east-1", "dimension": 1024, "record_count": 98, "namespace_count": 3, "size_bytes": 1069169, "created_at": "2025-05-14T16:37:25.625540Z" } ], "pagination": null } ``` # List restore jobs Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/list_restore_jobs https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_control_2026-04.oas.yaml get /restore-jobs List all restore jobs for a project. ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl "https://api.pinecone.io/restore-jobs" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Api-Key: $PINECONE_API_KEY" ``` ```json curl theme={null} { "data": [ { "restore_job_id": "9857add2-99d4-4399-870e-aa7f15d8d326", "backup_id": "94a63aeb-efae-4f7a-b059-75d32c27ca57", "target_index_name": "restored-index", "target_index_id": "0d8aed24-adf8-4b77-8e10-fd674309dc85", "status": "Completed", "created_at": "2025-04-25T18:14:05.227526Z", "completed_at": "2025-04-25T18:14:11.074618Z", "percent_complete": 100 }, { "restore_job_id": "69acc1d0-9105-4fcb-b1db-ebf97b285c5e", "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "target_index_name": "restored-index2", "target_index_id": "e6c0387f-33db-4227-9e91-32181106e56b", "status": "Completed", "created_at": "2025-05-14T17:25:59.378989Z", "completed_at": "2025-05-14T17:26:23.997284Z", "percent_complete": 100 } ], "pagination": null } ``` # Update backup schedule Source: https://docs.pinecone.io/reference/api/2026-04/control-plane/update_backup_schedule PATCH https://api.pinecone.io/backup-schedules/{schedule_id} Update a Pinecone backup schedule using the API, including pausing with enabled, changing frequency, and adjusting the retention expire_after_days. This endpoint requires `X-Pinecone-API-Version: unstable`. Update a backup schedule. Send only the fields you want to change. All body fields are optional. ### Path parameters The ID of the backup schedule to update. ### Body parameters Whether the schedule is enabled. Set to `false` to pause the schedule without deleting it. How often backups are created. One of `daily`, `weekly`, or `monthly`. The retention policy for backups created by this schedule. The number of days after which backups created by this schedule are automatically deleted. ```bash curl theme={null} curl -sS -X PATCH "https://api.pinecone.io/backup-schedules/${SCHEDULE_ID}" \ -H "api-key: ${PINECONE_API_KEY}" \ -H "X-Pinecone-API-Version: unstable" \ -H "Content-Type: application/json" \ -d '{ "enabled": false, "frequency": "weekly", "retention": { "expire_after_days": 14 } }' ``` ```json curl theme={null} { "schedule_id": "c688ed12-5a39-4254-9518-bd394b7f4886", "name": "my-nightly-backup", "index_id": "d40265e4-a492-402b-9cf1-973b4908b7a0", "project_id": "cc95c601-bf08-4973-9a1d-a65a1b528759", "schedule_type": "time-based", "frequency": "weekly", "retention_expire_after_days": 14, "enabled": false, "next_scheduled_run": "2026-04-24T06:00:00+00:00", "created_at": "2026-04-23T16:36:51.267528+00:00" } ``` # Cancel an import Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/cancel_import https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml delete /bulk/imports/{id} Cancel an import operation if it is not yet finished. It has no effect if the operation is already finished. For guidance and examples, see [Import data](https://docs.pinecone.io/guides/index-data/import-data). This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X DELETE "https://$INDEX_HOST/bulk/imports/101" \ -H 'Api-Key: $PINECONE_API_KEY' \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} {} ``` # Delete records Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/delete https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml post /vectors/delete Delete records by id or by metadata from a single namespace. For guidance and examples, see [Delete data](https://docs.pinecone.io/guides/manage-data/delete-data). ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/vectors/delete" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" \ -d '{ "ids": [ "id-1", "id-2" ], "namespace": "example-namespace" } ' ``` ```json curl theme={null} {} ``` # Describe an import Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/describe_import https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml get /bulk/imports/{id} Return details of a specific import operation. For guidance and examples, see [Import data](https://docs.pinecone.io/guides/index-data/import-data). This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/bulk/imports/101" \ -H 'Api-Key: $PINECONE_API_KEY' \ -H 'X-Pinecone-Api-Version: 2026-04' ``` ```json curl theme={null} { "id": "101", "uri": "s3://BUCKET_NAME/PATH/TO/DIR", "status": "Pending", "created_at": "2024-08-19T20:49:00.754Z", "finished_at": "2024-08-19T20:49:00.754Z", "percent_complete": 42.2, "records_imported": 1000000 } ``` # List record IDs Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/list https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml get /vectors/list List the IDs of records in a single namespace of a serverless index. An optional prefix can be passed to limit the results to IDs with a common prefix. Returns up to 100 IDs at a time by default in sorted order (bitwise "C" collation). If the `limit` parameter is set, `list` returns up to that number of IDs instead. Whenever there are additional IDs to return, the response also includes a `pagination_token` that you can use to get the next batch of IDs. When the response does not include a `pagination_token`, there are no more IDs to return. For guidance and examples, see [List record IDs](https://docs.pinecone.io/guides/manage-data/list-record-ids). **Note:** `list` is supported only for serverless indexes. ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/vectors/list?namespace=example-namespace&prefix=doc1#&limit=3" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "vectors": [ { "id": "doc1#chunk1" }, { "id": "doc1#chunk2" }, { "id": "doc1#chunk3" } ], "pagination": { "next": "c2Vjb25kY2FsbA==" }, "namespace": "example-namespace", "usage": { "readUnits": 1 } } ``` # List imports Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/list_imports https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml get /bulk/imports List all recent and ongoing import operations. By default, `list_imports` returns up to 100 imports per page. If the `limit` parameter is set, `list` returns up to that number of imports instead. Whenever there are additional IDs to return, the response also includes a `pagination_token` that you can use to get the next batch of imports. When the response does not include a `pagination_token`, there are no more imports to return. For guidance and examples, see [Import data](https://docs.pinecone.io/guides/index-data/import-data). This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/bulk/imports?paginationToken==Tm90aGluZyB0byBzZWUgaGVyZQo" \ -H 'Api-Key: $PINECONE_API_KEY' \ -H 'X-Pinecone-Api-Version: 2026-04' ``` ```json curl theme={null} { "data": [ { "id": "1", "uri": "s3://BUCKET_NAME/PATH/TO/DIR", "status": "Pending", "started_at": "2024-08-19T20:49:00.754Z", "finished_at": "2024-08-19T20:49:00.754Z", "percent_complete": 42.2, "records_imported": 1000000 } ], "pagination": { "next": "Tm90aGluZyB0byBzZWUgaGVyZQo=" } } ``` # Search with a vector Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/query https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml post /query Search a namespace using a query vector. It retrieves the ids of the most similar items in a namespace, along with their similarity scores. For guidance, examples, and limits, see [Search](https://docs.pinecone.io/guides/search/search-overview). ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/query" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" \ -d '{ "namespace": "example-namespace", "vector": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3], "filter": {"genre": {"$eq": "documentary"}}, "topK": 3, "includeValues": true }' ``` ```json curl theme={null} { "matches":[ { "id": "vec3", "score": 0, "values": [0.3,0.3,0.3,0.3,0.3,0.3,0.3,0.3] }, { "id": "vec2", "score": 0.0800000429, "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2] }, { "id": "vec4", "score": 0.0799999237, "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4] } ], "namespace": "example-namespace", "usage": {"read_units": 6} } ``` # Search with text Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/search_records https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml post /records/namespaces/{namespace}/search Search a namespace with a query text, query vector, or record ID and return the most similar records, along with their similarity scores. Optionally, rerank the initial results based on their relevance to the query. Searching with text is supported only for indexes with [integrated embedding](https://docs.pinecone.io/guides/index-data/indexing-overview#vector-embedding). Searching with a query vector or record ID is supported for all indexes. For guidance and examples, see [Search](https://docs.pinecone.io/guides/search/search-overview). ```shell curl theme={null} INDEX_HOST="INDEX_HOST" NAMESPACE="YOUR_NAMESPACE" PINECONE_API_KEY="YOUR_API_KEY" # Search with a query text and rerank the results # Supported only for indexes with integrated embedding curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" \ -d '{ "query": { "inputs": {"text": "Disease prevention"}, "top_k": 4, }, "fields": ["category", "chunk_text"] "rerank": { "model": "bge-reranker-v2-m3", "top_n": 2, "rank_fields": ["chunk_text"] # Specified field must also be included in 'fields' } }' # Search with a query vector and rerank the results curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" \ -d '{ "query": { "vector": { "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3] }, "top_k": 4, }, "fields": ["category", "chunk_text"] "rerank": { "query": "Disease prevention", "model": "bge-reranker-v2-m3", "top_n": 2, "rank_fields": ["chunk_text"] # Specified field must also be included in 'fields' } }' # Search with a record ID and rerank the results # Supported only for indexes with integrated embedding curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" \ -d '{ "query": { "id": "rec1", "top_k": 4, }, "fields": ["category", "chunk_text"] "rerank": { "query": "Disease prevention", "model": "bge-reranker-v2-m3", "top_n": 2, "rank_fields": ["chunk_text"] } }' ``` ```json curl theme={null} { "result": { "hits": [ { "_id": "rec3", "_score": 0.004433765076100826, "fields": { "category": "immune system", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases." } }, { "_id": "rec4", "_score": 0.0029121784027665854, "fields": { "category": "endocrine system", "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes." } } ] }, "usage": { "embed_total_tokens": 8, "read_units": 6, "rerank_units": 1 } } ``` # Start import Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/start_import https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml post /bulk/imports Start an asynchronous import of vectors from object storage into an index. For guidance and examples, see [Import data](https://docs.pinecone.io/guides/index-data/import-data). This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/bulk/imports" \ -H 'Api-Key: $PINECONE_API_KEY' \ -H 'Content-Type: application/json' \ -H 'X-Pinecone-Api-Version: 2026-04' \ -d '{ "integrationId": "a12b3d4c-47d2-492c-a97a-dd98c8dbefde", "uri": "s3://BUCKET_NAME/PATH/TO/DIR", "errorMode": { "onError": "continue" } }' ``` ```json curl theme={null} { "id": "101" } ``` # Update a record Source: https://docs.pinecone.io/reference/api/2026-04/data-plane/update https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/db_data_2026-04.oas.yaml post /vectors/update Update records by ID or by metadata in a namespace. Updating by ID changes the vector and/or metadata of a single record. Updating by metadata changes metadata across multiple records using a metadata filter. If a vector value is included, it will overwrite the previous value. If `set_metadata` is included, only the specified metadata fields are modified, and if a specified metadata field does not exist, it is added. For guidance and examples, see [Update data](https://docs.pinecone.io/guides/manage-data/update-data). ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/vectors/update" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" \ -d '{ "id": "id-3", "values": [4.0, 2.0], "setMetadata": {"type": "comedy"}, "namespace": "example-namespace" }' ``` ```json curl theme={null} {} ``` # Describe a model Source: https://docs.pinecone.io/reference/api/2026-04/inference/describe_model https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/inference_2026-04.oas.yaml get /models/{model_name} Get a description of a model hosted by Pinecone. You can use hosted models as an integrated part of Pinecone operations or for standalone embedding and reranking. For more details, see [Vector embedding](https://docs.pinecone.io/guides/index-data/indexing-overview#vector-embedding) and [Rerank results](https://docs.pinecone.io/guides/search/rerank-results). ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl "https://api.pinecone.io/models/llama-text-embed-v2" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "model": "llama-text-embed-v2", "short_description": "A high performance dense embedding model optimized for multilingual and cross-lingual text question-answering retrieval with support for long documents (up to 2048 tokens) and dynamic embedding size (Matryoshka Embeddings).", "type": "embed", "vector_type": "dense", "default_dimension": 1024, "modality": "text", "max_sequence_length": 2048, "max_batch_size": 96, "provider_name": "NVIDIA", "supported_metrics": [ "Cosine", "DotProduct" ], "supported_dimensions": [ 384, 512, 768, 1024, 2048 ], "supported_parameters": [ { "parameter": "input_type", "required": true, "type": "one_of", "value_type": "string", "allowed_values": [ "query", "passage" ] }, { "parameter": "truncate", "required": false, "default": "END", "type": "one_of", "value_type": "string", "allowed_values": [ "END", "NONE", "START" ] }, { "parameter": "dimension", "required": false, "default": 1024, "type": "one_of", "value_type": "integer", "allowed_values": [ 384, 512, 768, 1024, 2048 ] } ] } ``` # Generate vectors Source: https://docs.pinecone.io/reference/api/2026-04/inference/generate-embeddings https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/inference_2026-04.oas.yaml post /embed Generate vector embeddings for input data. This endpoint uses Pinecone's [hosted embedding models](https://docs.pinecone.io/guides/index-data/create-an-index#embedding-models). ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl https://api.pinecone.io/embed \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" \ -d '{ "model": "llama-text-embed-v2", "parameters": { "input_type": "passage", "truncate": "END" }, "inputs": [ {"text": "Apple is a popular fruit known for its sweetness and crisp texture."}, {"text": "The tech company Apple is known for its innovative products like the iPhone."}, {"text": "Many people enjoy eating apples as a healthy snack."}, {"text": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."}, {"text": "An apple a day keeps the doctor away, as the saying goes."}, {"text": "Apple Computer Company was founded on April 1, 1976, by Steve Jobs, Steve Wozniak, and Ronald Wayne as a partnership."} ] }' ``` ```json curl theme={null} { "data": [ { "values": [ 0.04925537109375, -0.01313018798828125, -0.0112762451171875, ... ] }, ... ], "model": "llama-text-embed-v2", "usage": { "total_tokens": 130 } } ``` # List available models Source: https://docs.pinecone.io/reference/api/2026-04/inference/list_models https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/inference_2026-04.oas.yaml get /models List the embedding and reranking models hosted by Pinecone. You can use hosted models as an integrated part of Pinecone operations or for standalone embedding and reranking. For more details, see [Vector embedding](https://docs.pinecone.io/guides/index-data/indexing-overview#vector-embedding) and [Rerank results](https://docs.pinecone.io/guides/search/rerank-results). ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl "https://api.pinecone.io/models" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" ``` ```json curl theme={null} { "models": [ { "model": "llama-text-embed-v2", "short_description": "A high performance dense embedding model optimized for multilingual and cross-lingual text question-answering retrieval with support for long documents (up to 2048 tokens) and dynamic embedding size (Matryoshka Embeddings).", "type": "embed", "vector_type": "dense", "default_dimension": 1024, "modality": "text", "max_sequence_length": 2048, "max_batch_size": 96, "provider_name": "NVIDIA", "supported_metrics": [ "Cosine", "DotProduct" ], "supported_dimensions": [ 384, 512, 768, 1024, 2048 ], "supported_parameters": [ { "parameter": "input_type", "required": true, "type": "one_of", "value_type": "string", "allowed_values": [ "query", "passage" ] }, { "parameter": "truncate", "required": false, "default": "END", "type": "one_of", "value_type": "string", "allowed_values": [ "END", "NONE", "START" ] }, { "parameter": "dimension", "required": false, "default": 1024, "type": "one_of", "value_type": "integer", "allowed_values": [ 384, 512, 768, 1024, 2048 ] } ] }, { "model": "multilingual-e5-large", "short_description": "A high-performance dense embedding model trained on a mixture of multilingual datasets. It works well on messy data and short queries expected to return medium-length passages of text (1-2 paragraphs)", "type": "embed", "vector_type": "dense", "default_dimension": 1024, "modality": "text", "max_sequence_length": 507, "max_batch_size": 96, "provider_name": "Microsoft", "supported_metrics": [ "Cosine", "Euclidean" ], "supported_dimensions": [ 1024 ], "supported_parameters": [ { "parameter": "input_type", "required": true, "type": "one_of", "value_type": "string", "allowed_values": [ "query", "passage" ] }, { "parameter": "truncate", "required": false, "default": "END", "type": "one_of", "value_type": "string", "allowed_values": [ "END", "NONE" ] } ] }, { "model": "pinecone-sparse-english-v0", "short_description": "A sparse embedding model for converting text to sparse vectors for keyword or hybrid semantic/keyword search. Built on the innovations of the DeepImpact architecture.", "type": "embed", "vector_type": "sparse", "modality": "text", "max_sequence_length": 512, "max_batch_size": 96, "provider_name": "Pinecone", "supported_metrics": [ "DotProduct" ], "supported_parameters": [ { "parameter": "input_type", "required": true, "type": "one_of", "value_type": "string", "allowed_values": [ "query", "passage" ] }, { "parameter": "truncate", "required": false, "default": "END", "type": "one_of", "value_type": "string", "allowed_values": [ "END", "NONE" ] }, { "parameter": "return_tokens", "required": false, "default": false, "type": "any", "value_type": "boolean" } ] }, { "model": "bge-reranker-v2-m3", "short_description": "A high-performance, multilingual reranking model that works well on messy data and short queries expected to return medium-length passages of text (1-2 paragraphs)", "type": "rerank", "modality": "text", "max_sequence_length": 1024, "max_batch_size": 100, "provider_name": "BAAI", "supported_parameters": [ { "parameter": "truncate", "required": false, "default": "NONE", "type": "one_of", "value_type": "string", "allowed_values": [ "END", "NONE" ] } ] }, { "model": "cohere-rerank-3.5", "short_description": "Cohere's leading reranking model, balancing performance and latency for a wide range of enterprise search applications.", "type": "rerank", "modality": "text", "max_sequence_length": 40000, "max_batch_size": 200, "provider_name": "Cohere", "supported_parameters": [ { "parameter": "max_chunks_per_doc", "required": false, "default": 3072, "type": "numeric_range", "value_type": "integer", "min": 1, "max": 3072 } ] }, { "model": "pinecone-rerank-v0", "short_description": "A state of the art reranking model that out-performs competitors on widely accepted benchmarks. It can handle chunks up to 512 tokens (1-2 paragraphs)", "type": "rerank", "modality": "text", "max_sequence_length": 512, "max_batch_size": 100, "provider_name": "Pinecone", "supported_parameters": [ { "parameter": "truncate", "required": false, "default": "END", "type": "one_of", "value_type": "string", "allowed_values": [ "END", "NONE" ] } ] } ] } ``` # Rerank results Source: https://docs.pinecone.io/reference/api/2026-04/inference/rerank https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/inference_2026-04.oas.yaml post /rerank Rerank results according to their relevance to a query. For guidance and examples, see [Rerank results](https://docs.pinecone.io/guides/search/rerank-results). ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl https://api.pinecone.io/rerank \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "X-Pinecone-Api-Version: 2026-04" \ -H "Api-Key: $PINECONE_API_KEY" \ -d '{ "model": "bge-reranker-v2-m3", "query": "The tech company Apple is known for its innovative products like the iPhone.", "return_documents": true, "top_n": 4, "documents": [ {"id": "vec1", "text": "Apple is a popular fruit known for its sweetness and crisp texture."}, {"id": "vec2", "text": "Many people enjoy eating apples as a healthy snack."}, {"id": "vec3", "text": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."}, {"id": "vec4", "text": "An apple a day keeps the doctor away, as the saying goes."} ], "parameters": { "truncate": "END" } }' ``` ```JSON curl theme={null} { "data":[ { "index":2, "document":{ "id":"vec3", "text":"Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces." }, "score":0.47654688 }, { "index":0, "document":{ "id":"vec1", "text":"Apple is a popular fruit known for its sweetness and crisp texture." }, "score":0.047963805 }, { "index":3, "document":{ "id":"vec4", "text":"An apple a day keeps the doctor away, as the saying goes." }, "score":0.007587992 }, { "index":1, "document":{ "id":"vec2", "text":"Many people enjoy eating apples as a healthy snack." }, "score":0.0006491712 } ], "usage":{ "rerank_units":1 } } ``` # Authentication Source: https://docs.pinecone.io/reference/api/authentication Pinecone API authentication guide covering API key generation, SDK client setup, and HTTP header configuration for authorized requests. All requests to [Pinecone APIs](/reference/api/introduction) must contain a valid [API key](/guides/production/security-overview#api-keys) for the target project. ## Get an API key [Create a new API key](https://app.pinecone.io/organizations/-/projects/-/keys) in the Pinecone console, or use the connect widget below to generate a key.
Copy your generated key: ``` PINECONE_API_KEY="{{YOUR_API_KEY}}" # This API key has ReadWrite access to all indexes in your project. ``` ## Initialize a client When using a [Pinecone SDK](/reference/pinecone-sdks), initialize a client object with your API key and then reuse the authenicated client in subsquent function calls. For example: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key='YOUR_API_KEY') # Creates an index using the API key stored in the client 'pc'. pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud='aws', region='us-east-1' ) ) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); // Creates an index using the API key stored in the client 'pc'. await pc.createIndex({ name: 'docs-example', dimension: 1536, metric: 'cosine', spec: { serverless: { cloud: 'aws', region: 'us-east-1' } } }) ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.IndexModel; import org.openapitools.db_control.client.model.DeletionProtection; public class CreateServerlessIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); // Creates an index using the API key stored in the client 'pc'. pc.createServerlessIndex("docs-example", "cosine", 1536, "aws", "us-east-1"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v3/pinecone" ) 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) } indexName := "docs-example" vectorType := "dense" dimension := int32(1536) metric := pinecone.Cosine deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: indexName, VectorType: &vectorType, Dimension: &dimension, Metric: &metric, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: &deletionProtection, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", err) } else { fmt.Printf("Successfully created serverless index: %v", idx.Name) } } ``` ```shell curl theme={null} curl -s "https://api.pinecone.io/indexes" \ -H "Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud":"aws", "region": "us-east-1" } } }' ``` ## Add headers to an HTTP request All HTTP requests to Pinecone APIs must contain an `Api-Key` header that specifies a valid [API key](/guides/production/security-overview#api-keys) and must be encoded as JSON with the `Content-Type: application/json` header. For example: ```shell curl theme={null} curl https://api.pinecone.io/indexes \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud":"aws", "region": "us-east-1" } } }' ``` ## Troubleshooting Older versions of Pinecone required you to initialize a client with an `init` method that takes both `api_key` and `environment` parameters, for example: ```python Python theme={null} # Legacy initialization import pinecone pc = pinecone.init( api_key="PINECONE_API_KEY", environment="PINECONE_ENVIRONMENT" ) ``` ```javascript JavaScript theme={null} // Legacy initialization import { Pinecone } from '@pinecone-database/pinecone'; const pineconeClient = new PineconeClient(); await pineconeClient.init({ apiKey: 'PINECONE_API_KEY', environment: 'PINECONE_ENVIRONMENT', }); ``` In more recent versions of Pinecone, this has changed. Initialization no longer requires an `init` step, and cloud environment is defined for each index rather than an entire project. Client initialization now only requires an `api_key` parameter, for example: ```python Python theme={null} # New initialization from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` ```javascript JavaScript theme={null} // New initialization import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); ``` If you are receiving errors about initialization, upgrade your [Pinecone SDK](/reference/pinecone-sdks) to the latest version, for example: ```shell Python theme={null} # Upgrade Pinecone SDK pip install pinecone --upgrade ``` ```shell JavaScript theme={null} # Upgrade Pinecone SDK npm install @pinecone-database/pinecone@latest ``` Also, note that some third-party tutorials and examples still reference the older initialization method. In such cases, follow the example above and the examples throughout the Pinecone documentation instead. # Pinecone Database limits Source: https://docs.pinecone.io/reference/api/database-limits Reference for Pinecone Database limits, covering upsert, query, fetch, delete, import, namespace, and rate limits for serverless indexes. This page describes different types of limits for Pinecone Database. **Looking for a specific limit?** * To compare monthly included usage by plan, start with [read units](#read-units-per-month-per-org), [write units](#write-units-per-month-per-org), and [model usage limits](#monthly-usage-limits). * If you received a `429` error, check [rate limits](#rate-limits), especially request-per-second limits for query, upsert, update, delete, fetch, and list. * For projects, users, indexes, namespaces, storage, backups, and collections, see [object limits](#object-limits). * For batch sizes, metadata filters, and identifier lengths, see [operation limits](#operation-limits) and [identifier limits](#identifier-limits). ## Rate limits Rate limits help protect your applications from misuse and maintain the health of our shared serverless infrastructure. These limits are designed to support typical production workloads while ensuring reliable performance for all users. **Most rate limits can be adjusted upon request.** If you need higher limits to scale your application, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. Pinecone is committed to supporting your growth and can often accommodate higher throughput requirements. Rate limits vary based on [pricing plan](https://www.pinecone.io/pricing/) and apply to [serverless indexes](/guides/index-data/indexing-overview) only. Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Data plane operations: request-per-second limits Pinecone enforces rate limits on the number of API requests per second at the namespace level for data plane operations (query, upsert, delete, and update). These limits provide protection against excessive request rates. #### Affected operations The following operations are subject to request-per-second rate limiting: | Operation | Scope | Limit | | --------- | ------------- | ----- | | Query | Per namespace | 100 | | Upsert | Per namespace | 100 | | Delete | Per namespace | 100 | | Update | Per namespace | 100 | #### Error response When you exceed the request-per-second limit, you'll receive an HTTP `429 - TOO_MANY_REQUESTS` response. The error message indicates which operation exceeded the limit and includes the namespace name and limit value. See the individual limit sections below for specific error message formats. #### How request-per-second limits work with limits on read and write units Request-per-second limits are enforced in addition to existing read unit and write unit limits. Requests must not exceed any applicable limits: * Index-level limits - read and write unit limits, per index * Namespace-level limits - read and write unit limits, per namespace * Request-per-second limits - requests per second, per namespace If any limit is exceeded, the request fails with a 429 error. #### Recommendations If you're hitting request-per-second limits: 1. Implement retry logic. Use exponential backoff to handle rate limit errors gracefully. See [Error Handling Guide](/guides/production/error-handling#implement-retry-logic). 2. Pace your requests. Add client-side rate limiting to stay under limits. 3. Consider [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes), which don't have request-per-second limits and provide dedicated capacity for high-throughput workloads. 4. If you need higher limits, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. ### All rate limits #### Monthly usage limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :---------------------------------------------------------------------------- | :------------- | :------------- | :------------- | :-------------- | | [Read units per month per org](#read-units-per-month-per-org) | 1,000,000 | 2,000,000 | Unlimited | Unlimited | | [Write units per month per org](#write-units-per-month-per-org) | 2,000,000 | 5,000,000 | Unlimited | Unlimited | | [Embedding tokens per month per model](#embedding-tokens-per-month-per-model) | 5,000,000 | 10,000,000 | Unlimited | Unlimited | | [Rerank requests per month per model](#rerank-requests-per-month-per-model) | Model-specific | Model-specific | Model-specific | Model-specific | #### Data operation throughput limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :------------------------------------------------------------------------------------------------------------ | :----------- | :----------- | :------------ | :-------------- | | [Upsert size per second per namespace](#upsert-size-per-second-per-namespace) | 50 MB | 50 MB | 50 MB | 50 MB | | [Query read units per second per index](#query-read-units-per-second-per-index) | 2,000 | 2,000 | 2,000 | 2,000 | | [Query requests per second per namespace](#query-requests-per-second-per-namespace) | 100 | 100 | 100 | 100 | | [Update records per second per namespace](#update-records-per-second-per-namespace) | 100 | 100 | 100 | 100 | | [Update requests per second per namespace](#update-requests-per-second-per-namespace) | 100 | 100 | 100 | 100 | | [Update by metadata requests per second per namespace](#update-by-metadata-requests-per-second-per-namespace) | 5 | 5 | 5 | 5 | | [Update by metadata requests per second per index](#update-by-metadata-requests-per-second-per-index) | 500 | 500 | 500 | 500 | | [Upsert requests per second per namespace](#upsert-requests-per-second-per-namespace) | 100 | 100 | 100 | 100 | | [Fetch requests per second per index](#fetch-requests-per-second-per-index) | 100 | 100 | 100 | 100 | | [List requests per second per index](#list-requests-per-second-per-index) | 200 | 200 | 200 | 200 | | [Describe index stats requests per second per index](#describe-index-stats-requests-per-second-per-index) | 100 | 100 | 100 | 100 | | [Delete requests per second per namespace](#delete-requests-per-second-per-namespace) | 100 | 100 | 100 | 100 | | [Delete records per second per namespace](#delete-records-per-second-per-namespace) | 5,000 | 5,000 | 5,000 | 5,000 | | [Delete records per second per index](#delete-records-per-second-per-index) | 5,000 | 5,000 | 5,000 | 5,000 | | [Delete by metadata requests per second per namespace](#delete-by-metadata-requests-per-second-per-namespace) | 5 | 5 | 5 | 5 | | [Delete by metadata requests per second per index](#delete-by-metadata-requests-per-second-per-index) | 500 | 500 | 500 | 500 | #### Model throughput limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :------------------------------------------------------------------------------ | :------------- | :------------- | :------------- | :-------------- | | [Embedding tokens per minute per model](#embedding-tokens-per-minute-per-model) | Model-specific | Model-specific | Model-specific | Model-specific | | [Rerank requests per minute per model](#rerank-requests-per-minute-per-model) | Model-specific | Model-specific | Model-specific | Model-specific | ### Read units per month per org | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 1,000,000 | 2,000,000 | Unlimited | Unlimited | [Read units](/guides/manage-cost/understanding-cost#read-units) measure the compute, I/O, and network resources used by [fetch](/guides/manage-data/fetch-data), [query](/guides/search/search-overview), and [list](/guides/manage-data/list-record-ids) requests to serverless indexes. When you reach the monthly read unit limit for an organization, fetch, query, and list requests to serverless indexes in the organization will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached your read unit limit for the current month limit. To continue reading data, upgrade your plan. ``` To continue reading from serverless indexes in the organization, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). To check how close you are to the monthly read unit limit for your organization, do the following: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select the project. 3. Select any index in the project. 4. Look under **Usage**. Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Write units per month per org | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 2,000,000 | 5,000,000 | Unlimited | Unlimited | [Write units](/guides/manage-cost/understanding-cost#write-units) measure the storage and compute resources used by [upsert](/guides/index-data/upsert-data), [update](/guides/manage-data/update-data), and [delete](/guides/manage-data/delete-data) requests to serverless indexes. When you reach the monthly write unit limit for an organization, upsert, update, and delete requests to serverless indexes in the organization will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached your write unit limit for the current month. To continue writing data, upgrade your plan. ``` To continue writing data to serverless indexes in the organization, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). To check how close you are to the monthly write unit limit for your organization, do the following: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select the project. 3. Select any index in the project. 4. Look under **Usage**. ### Upsert size per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 50 MB | 50 MB | 50 MB | 50 MB | When you reach the per second [upsert](/guides/index-data/upsert-data) size for a namespace in an index, additional upserts will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max upsert size limit per second for index . Pace your upserts or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Query read units per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 2,000 | 2,000 | 2,000 | 2,000 | Pinecone measures [query](/guides/search/search-overview) usage in [read units](/guides/manage-cost/understanding-cost#read-units). When you reach the per second limit for queries across all namespaces in an index, additional queries will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max query read units per second for index . Pace your queries or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). To check how many read units a query consumes, [check the query response](/guides/manage-cost/monitor-usage-and-costs#read-units). Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Query requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [query](/guides/search/search-overview) limit for a namespace in an index, additional queries will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the query QPS limit for namespace {namespace_name} ({limit} QPS). Pace your queries, consider Dedicated Read Nodes for your index, or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Update records per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [update](/guides/manage-data/update-data) limit for a namespace in an index, additional updates will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max update records per second for namespace . Pace your update requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Update requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [update](/guides/manage-data/update-data) request limit for a namespace in an index, additional update requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the update QPS limit for namespace {namespace_name} ({limit} QPS). Pace your update requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). If you need to update most of the records in a large namespace, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) for help creating an export to enable a faster and more cost-effective approach. ### Update by metadata requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5 | 5 | 5 | 5 | When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit for a namespace in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max update by metadata requests per second for namespace . Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Update by metadata requests per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 500 | 500 | 500 | 500 | When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit across all namespaces in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max update by metadata requests per second for index . Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Upsert requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [upsert](/guides/index-data/upsert-data) request limit for a namespace in an index, additional upsert requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the upsert QPS limit for namespace {namespace_name} ({limit} QPS). Pace your upsert requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Fetch requests per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [fetch](/guides/manage-data/fetch-data) limit across all namespaces in an index, additional fetch requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max fetch requests per second for index . Pace your fetch requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### List requests per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 200 | 200 | 200 | 200 | When you reach the per second [list](/guides/manage-data/list-record-ids) limit across all namespaces in an index, additional list requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max list requests per second for index . Pace your list requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Describe index stats requests per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [describe index stats](/reference/api/2024-10/data-plane/describeindexstats) limit across all namespaces in an index, additional describe index stats requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max describe_index_stats requests per second for index . Pace your describe_index_stats requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [delete](/guides/manage-data/delete-data) request limit for a namespace in an index, additional delete requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the delete QPS limit for namespace {namespace_name} ({limit} QPS). Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete records per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5000 | 5000 | 5000 | 5000 | When you reach the per second [delete](/guides/manage-data/delete-data) limit for a namespace in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete records per second for namespace . Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete records per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5000 | 5000 | 5000 | 5000 | When you reach the per second [delete](/guides/manage-data/delete-data) limit across all namespaces in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete records per second for index . Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete by metadata requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5 | 5 | 5 | 5 | When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit for a namespace in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete by metadata requests per second for namespace . Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete by metadata requests per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 500 | 500 | 500 | 500 | When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit across all namespaces in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete by metadata requests per second for index . Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Embedding tokens per minute per model | Embedding model | Input type | Starter plan | Builder plan | Standard plan | Enterprise plan | | :--------------------------- | :--------- | :----------- | :----------- | :------------ | :-------------- | | `llama-text-embed-v2` | Passage | 250,000 | 250,000 | 1,000,000 | 1,000,000 | | | Query | 50,000 | 50,000 | 250,000 | 250,000 | | `multilingual-e5-large` | Passage | 250,000 | 250,000 | 1,000,000 | 1,000,000 | | | Query | 50,000 | 50,000 | 250,000 | 250,000 | | `pinecone-sparse-english-v0` | Passage | 250,000 | 250,000 | 3,000,000 | 3,000,000 | | | Query | 250,000 | 250,000 | 3,000,000 | 3,000,000 | When you reach the per minute token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max embedding tokens per minute () model ''' and input type '' for the current project. To increase this limit, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). Otherwise, you can handle this limit by [implementing retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). ### Embedding tokens per month per model | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5,000,000 | 10,000,000 | Unlimited | Unlimited | When you reach the monthly token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the embedding token limit () for model for the current month. To continue using this model, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Rerank requests per minute per model | Reranking model | Starter plan | Builder plan | Standard plan | Enterprise plan | | :--------------------- | :------------ | :------------ | :------------ | :-------------- | | `cohere-rerank-4-fast` | Not available | Not available | 300 | 300 | | `cohere-rerank-3.5` | Not available | Not available | 300 | 300 | | `bge-reranker-v2-m3` | 60 | 60 | 60 | 60 | | `pinecone-rerank-v0` | 60 | Not available | 60 | 60 | When you reach the per minute request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max rerank requests per minute () for model '' for the current project. To increase this limit, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Rerank requests per month per model | Reranking model | Starter plan | Builder plan | Standard plan | Enterprise plan | | :--------------------- | :------------ | :------------ | :------------ | :-------------- | | `cohere-rerank-4-fast` | Not available | Not available | Unlimited | Unlimited | | `cohere-rerank-3.5` | Not available | Not available | Unlimited | Unlimited | | `bge-reranker-v2-m3` | 500 | 1,000 | Unlimited | Unlimited | | `pinecone-rerank-v0` | 500 | Not available | Unlimited | Unlimited | When you reach the monthly request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the rerank request limit () for model for the current month. To continue using this model, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Inference requests per second or minute, per project | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :---------------------------- | :----------- | :----------- | :------------ | :-------------- | | Inference requests per second | 100 | 100 | 100 | 100 | | Inference requests per minute | 2000 | 2000 | 2000 | 2000 | When you reach the per second or per minute request limit, inference requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max inference requests per second () for the current project. ``` This error indicates per second or per minute, as applicable. To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). ## Object limits Object limits are restrictions on the number or size of objects in Pinecone. Object limits vary based on [pricing plan](https://www.pinecone.io/pricing/). | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :----------------------------------------------------------------------------- | :----------- | :----------- | :------------ | :-------------- | | [Projects per organization](#projects-per-organization) | 1 | 5 | 20 | 100 | | [Users per organization](#users-per-organization) | 2 | 5 | Unlimited | Unlimited | | [Serverless indexes per project](#serverless-indexes-per-project) 1 | 5 | 10 | 20 | 200 | | [Serverless index storage per org](#serverless-index-storage-per-org) | 2 GB | 10 GB | N/A | N/A | | [Namespaces per serverless index](#namespaces-per-serverless-index) | 100 | 1,000 | 100,000 | 100,000 | | [Serverless backups per project](#serverless-backups-per-project) | N/A | N/A | 500 | 1000 | | [Collections per project](#collections-per-project) | 100 | N/A | N/A | N/A | 1 On the Starter plan, all serverless indexes must be in the `us-east-1` region of AWS. Builder, Standard, and Enterprise plans can create indexes in any [supported region](/guides/index-data/create-an-index#cloud-regions).
### Projects per organization | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 1 | 5 | 20 | 100 | When you reach this quota for an organization, trying to [create projects](/guides/projects/create-a-project) will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max projects allowed in organization . To add more projects, upgrade your plan. ``` To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Users per organization | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 2 | 5 | Unlimited | Unlimited | When you reach this quota for an organization, trying to add users to the organization will fail. To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Serverless indexes per project | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5 | 10 | 20 | 200 | When you reach this quota for a project, trying to [create serverless indexes](/guides/index-data/create-an-index#create-a-serverless-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max serverless indexes allowed in project . Use namespaces to partition your data into logical groups, or upgrade your plan to add more serverless indexes. ``` To stay under this quota, consider using [namespaces](/guides/index-data/create-an-index#namespaces) instead of creating multiple indexes. Namespaces let you partition your data into logical groups within a single index. This approach not only helps you stay within index limits, but can also improve query performance and lower costs by limiting searches to relevant data subsets. To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Serverless index storage per org This limit applies to organizations on the Starter and Builder plans only. | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 2 GB | 10 GB | N/A | N/A | When you've reached this quota for an organization, updates and upserts into serverless indexes will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max storage allowed for organization . To update or upsert new data, delete records or upgrade your plan. ``` To continue writing data into your serverless indexes, [delete records](/guides/manage-data/delete-data) to bring your organization under the limit or [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Namespaces per serverless index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 1,000 | 100,000 | 100,000 | When you reach this quota for a serverless index, trying to [upsert records into a new namespace](/guides/index-data/upsert-data) in the index will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max namespaces allowed in serverless index . To add more namespaces, upgrade your plan. ``` To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). [Namespaces per serverless index](/reference/api/database-limits#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](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Serverless backups per project | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | N/A | N/A | 500 | 1000 | Backups are not available on the Starter or Builder plans. On the Standard and Enterprise plans, when you reach this quota for a project, trying to [create serverless backups](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Backup failed to create. Quota for number of backups per index exceeded. ``` ### Collections per project | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | N/A | N/A | N/A | When you reach this quota for a project, trying to [create collections](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max collections allowed in project . To add more collections, upgrade your plan. ``` To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ## Operation limits Operation limits are restrictions on the size, number, or other characteristics of operations in Pinecone. Operation limits are fixed and do not vary based on pricing plan. ### Upsert limits | Metric | Limit | | :----------------------------------------------------------------- | :------------------------------------------------------------ | | Max [batch size](/guides/index-data/upsert-data#upsert-in-batches) | 2 MB or 1000 records with vectors
96 records with text | | Max documents per upsert request | 1000 | | Max document upsert request size | 2 MB | | Max document size | 2 MB | | Max `full_text_search` string fields per schema | 100 | | Max size per `full_text_search` string field | 100 KB | | Max tokens per `full_text_search` string field | 10,000 | | Max bytes per token | 256 bytes | | Max filterable metadata size per document | 40 KB | | Max length for a record ID | 512 characters | | Max dimensionality for dense vectors | 20,000 | | Max non-zero values for sparse vectors | 2048 | | Max dimensionality for sparse vectors | 4.2 billion | The 40 KB filterable metadata limit does not apply to `full_text_search` text fields. ### Import limits If your import exceeds these limits, you'll get an error specifying the limit exceeded. See [Troubleshooting](/guides/index-data/import-data#troubleshooting) for details. | Metric | Limit | | :-------------------------------------------- | :-------- | | Max namespaces per import | 10,000 | | Max total input data size (on-demand indexes) | 1 TB | | Max total input data size (DRN indexes) | Unlimited | | Max files per import | 100,000 | | Max size per file | 10 GB | The total input data size limit does not apply to indexes with [dedicated read nodes](/guides/index-data/dedicated-read-nodes). Bulk import supports indexes without a schema definition (Parquet files) and indexes with document schemas ([JSONL files](/guides/search/full-text-search#bulk-import)). Semantic-text (auto-embedded) fields are not yet supported in document schemas. ### Query limits | Metric | Limit | | :---------------- | :----- | | Max `top_k` value | 10,000 | | Max result size | 4MB | The query result size is affected by the dimension of the dense vectors and whether or not dense vector values and metadata are included in the result. If a query fails due to exceeding the 4MB result size limit, choose a lower `top_k` value, or use `include_metadata=False` or `include_values=False` to exclude metadata or values from the result. For better performance, especially with higher `top_k` values, avoid including vector values unless you need them. ### Fetch limits **Fetch by ID limits:** | Metric | Limit | | :------------------------------- | :---- | | Max record IDs per fetch request | 1,000 | **Fetch by metadata limits:** | Metric | Limit | | :----------------------- | :---------------------------------- | | Max records per response | 10,000 | | Max response size | 4 MB | | Max request rate | 5 requests per second per namespace | To retrieve more than 10,000 matching records, paginate through results using the `paginationToken` parameter. See [Fetch records by metadata](/guides/manage-data/fetch-data#fetch-records-by-metadata). ### Delete limits | Metric | Limit | | :-------------------------------- | :---- | | Max record IDs per delete request | 1,000 | ### Metadata filter limits The following limits apply to [metadata filter expressions](/guides/search/filter-by-metadata#metadata-filter-expressions) used in query, delete, update, and fetch operations. | Limit | Value | Description | | :------------------------------------------ | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Maximum values per `$in` or `$nin` operator | 10,000 | Each `$in` or `$nin` operator accepts up to 10,000 values in its array. This limit applies per operator—if you have multiple `$in` operators in a single filter, each is independently limited to 10,000 values. | When you exceed this limit, the request will fail and return a `400 - BAD_REQUEST` error. #### Rationale Large `$in` operators can impact query performance and cost. Filters with thousands of values increase request payload size and end-to-end latency. Additionally, using large filters typically indicates a shared namespace architecture, which increases query costs—queries scan the entire namespace regardless of filters. #### Alternative approaches If you need to filter by more than 10,000 values, consider these alternatives: * **Use namespaces for tenant isolation**: Instead of filtering by tenant IDs within a single namespace, create separate namespaces for each tenant or tenant group. This can also reduce query costs. See [Design for multi-tenancy](/guides/index-data/data-modeling#design-for-multi-tenancy). * **Use broader access control groups**: Instead of filtering by individual user IDs, filter by organization, project, or role. This reduces the number of values in your `$in` filter. See [Design for multi-tenancy](/guides/index-data/data-modeling#use-access-control-groups-instead-of-individual-ids). * **Post-filter client-side**: Retrieve a larger top K without filtering (for example, top 1000), then filter results client-side. * **Run multiple queries**: Split your filter into multiple queries with smaller `$in` operators and combine the results client-side. To avoid hitting this limit in production, validate the size of your `$in` and `$nin` arrays in your application code before making the request to Pinecone. ## Identifier limits An identifier is a string of characters used to identify "named" [objects in Pinecone](/guides/get-started/concepts). The following Pinecone objects use strings as identifiers: | Object | Field | Max # characters | Allowed characters | | --------------------------------------------------------- | ----------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | [Organization](/guides/get-started/concepts#organization) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Project](/guides/get-started/concepts#project) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Index](/guides/get-started/concepts#index) | `name` | 45 |
  • `a-z`, `0-9`, and `-`
  • Must be lowercase
  • Cannot start or end with `-`
  • Cannot be empty
| | [Namespace](/guides/get-started/concepts#namespace) | `namespace` | 512 |
  • ASCII except `\0`
  • For the default namespace, use `""` (or `"__default__"`, in API versions `2025-04` and later)
| | [Record](/guides/get-started/concepts#record) | `id` | 512 |
  • ASCII except `\0`
  • Cannot be empty
| # Errors Source: https://docs.pinecone.io/reference/api/errors Pinecone REST API: Pinecone uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the range. Pinecone uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that failed given the information provided, and codes in the `5xx` range indicate an error with Pinecone's servers. For guidance on handling errors in production, see [Error handling](/guides/production/error-handling). ## 200 - OK The request succeeded. ## 201 - CREATED The request succeeded and a new resource was created. ## 202 - NO CONTENT The request succeeded, but there is no content to return. ## 400 - INVALID ARGUMENT The request failed due to an invalid argument. ## 401 - UNAUTHENTICATED The request failed due to a missing or invalid [API key](/guides/projects/understanding-projects#api-keys). ## 402 - PAYMENT REQUIRED The request failed due to delinquent payment or account deactivation for non-payment. See [Account deactivation for non-payment](/guides/organizations/manage-billing/non-payment-account-deactivation). ## 403 - FORBIDDEN The request failed due to an exceeded [quota](/reference/api/database-limits#object-limits) or [index deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection). ## 404 - NOT FOUND The request failed because the resource was not found. ## 409 - ALREADY EXISTS The request failed because the resource already exists. ## 412 - FAILED PRECONDITIONS The request failed due to preconditions not being met. | ## 422 - UNPROCESSABLE ENTITY The request failed because the server was unable to process the contained instructions. ## 429 - TOO MANY REQUESTS The request was [rate-limited](/reference/api/database-limits#rate-limits). [Implement retry logic with exponential backoff](/guides/production/error-handling#handle-rate-limits-429) to handle this error. ## 500 - UNKNOWN An internal server error occurred. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. ## 502 - BAD GATEWAY The API gateway received an invalid response from a backend service. This is typically a temporary error. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. ## 503 - UNAVAILABLE The server is currently unavailable. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. ## 504 - GATEWAY TIMEOUT The API gateway did not receive a timely response from the backend server. This can occur due to slow requests or backend processing delays. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. # API reference Source: https://docs.pinecone.io/reference/api/introduction Pinecone API reference overview for Database, Inference, and Admin endpoints with supported SDKs including Python, Node.js, Java, and Go. Pinecone's APIs let you interact programmatically with your Pinecone account. [SDK versions](/reference/pinecone-sdks#sdk-versions) are pinned to specific API versions. ## Database Use the Database API to store and query records in [Pinecone Database](/guides/get-started/quickstart). The following Pinecone SDKs support the Database API: ## Inference Use the Inference API to generate vector embeddings and rerank results using [embedding models](/guides/index-data/create-an-index#embedding-models) and [reranking models](/guides/search/rerank-results#reranking-models) hosted on Pinecone's infrastructure. There are two ways to use the Inference API: * As a standalone service, through the [Rerank documents](/reference/api/latest/inference/rerank) and [Generate vectors](/reference/api/latest/inference/generate-embeddings) endpoints. * As an integrated part of database operations, through the [Create an index with integrated embedding](/reference/api/latest/control-plane/create_for_model), [Upsert text](/reference/api/latest/data-plane/upsert_records), and [Search with text](/reference/api/latest/data-plane/search_records) endpoints. The following Pinecone SDKs support using the Inference API: # Known limitations Source: https://docs.pinecone.io/reference/api/known-limitations Known limitations and feature restrictions for Pinecone indexes, including upsert consistency, metadata rules, and serverless caveats. This page describes known limitations and feature restrictions in Pinecone. ## General * [Upserts](/guides/index-data/upsert-data) * Pinecone is eventually consistent, so there can be a slight delay before upserted records are available to query. After upserting records, use the [`describe_index_stats`](/reference/api/2024-10/data-plane/describeindexstats) operation to check if the current vector count matches the number of records you expect, although this method may not work for pod-based indexes with multiple replicas. * Only indexes using the [dotproduct distance metric](/guides/index-data/indexing-overview#dotproduct) support querying sparse-dense vectors. Upserting, updating, and fetching sparse-dense vectors in indexes with a different distance metric will succeed, but querying will return an error. * Indexes created before February 22, 2023 do not support sparse vectors. * [Metadata](/guides/index-data/upsert-data#upsert-with-metadata-filters) * Null metadata values aren't supported. Instead of setting a key to `null`, remove the key from the metadata payload. * Nested JSON objects are not supported. ## Serverless indexes Serverless indexes do not support the following features: * [Filtering index statistics by metadata](/reference/api/2024-10/data-plane/describeindexstats) * [Private endpoints](/guides/production/configure-private-endpoints) * This feature is available on AWS only. # API versioning Source: https://docs.pinecone.io/reference/api/versioning Pinecone REST API: Pinecone's APIs are versioned to ensure that your applications continue to work as expected as the platform evolves. Pinecone's APIs are versioned to ensure that your applications continue to work as expected as the platform evolves. Versions are named by release date in the format `YYYY-MM`, for example, `2025-10`. ## Release schedule On a quarterly basis, Pinecone releases a new **stable** API version as well as a **release candidate** of the next stable version. * **Stable:** Each stable version remains unchanged and supported for a minimum of 12 months. Since stable versions are released every 3 months, this means you have at least 9 months to test and migrate your app to the newest stable version before support for the previous version is removed. * **Release candidate:** The release candidate gives you insight into the upcoming changes in the next stable version. It is available for approximately 3 months before the release of the stable version and can include new features, improvements, and [breaking changes](#breaking-changes). Below is an example of Pinecone's release schedule: ## Specify an API version When using the API directly, it is important to specify an API version in your requests. If you don't, requests default to the oldest supported stable version. Once support for that version ends, your requests will default to the next oldest stable version, which could include breaking changes that require you to update your integration. To specify an API version, set the `X-Pinecone-Api-Version` header to the version name. For example, to use the latest stable version (`2026-04`) to describe an index, set the `X-Pinecone-Api-Version` header: ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/indexes/movie-recommendations" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" ``` To use an older version, specify that version instead. ## SDK versions Official [Pinecone SDKs](/reference/pinecone-sdks) provide convenient access to Pinecone APIs. SDK versions are pinned to specific API versions. When a new API version is released, a new version of the SDK is also released. For the mapping between SDK and API versions, see [SDK versions](/reference/pinecone-sdks#sdk-versions). ## Breaking changes Breaking changes are changes that can potentially break your integration with a Pinecone API. Breaking changes include: * Removing an entire operation * Removing or renaming a parameter * Removing or renaming a response field * Adding a new required parameter * Making a previously optional parameter required * Changing the type of a parameter or response field * Removing enum values * Adding a new validation rule to an existing parameter * Changing authentication or authorization requirements ## Non-breaking changes Non-breaking changes are additive and should not break your integration. Additive changes include: * Adding an operation * Adding an optional parameter * Adding an optional request header * Adding a response field * Adding a response header * Adding enum values ## Get updates To ensure you always know about upcoming API changes, follow the [Release notes](/release-notes/). # CLI authentication Source: https://docs.pinecone.io/reference/cli/authentication Authenticate the Pinecone CLI using user login, service accounts, or API keys, including auth priority and Admin API access rules. This document describes how to authenticate the Pinecone CLI to manage your Pinecone resources. ## Authentication methods | Method | Admin API | Control/data plane | Best for | | ----------------------------------- | --------- | ------------------ | -------------------------------- | | [User login](#user-login) | ✅ | ✅ | Interactive use | | [Service account](#service-account) | ✅ | ✅ | Automation with Admin API access | | [API key](#api-key) | ❌ | ✅ | Simple automation, CI/CD | ### User login Authenticate through a web browser. The token refreshes automatically and stays valid for up to 120 days (re-auth required after 30 days of inactivity). ```bash theme={null} pc auth login ``` The CLI auto-targets your default organization and its first project. Change with `pc target -o "my-org" -p "my-project"`. ### Service account Authenticate with credentials from a [service account](/guides/organizations/manage-service-accounts). ```bash theme={null} pc auth configure --client-id "ID" --client-secret "SECRET" # Or via environment variables export PINECONE_CLIENT_ID="your-client-id" export PINECONE_CLIENT_SECRET="your-client-secret" ``` The CLI auto-targets the service account's organization. For projects: auto-selects if one exists, prompts if multiple exist, or set manually with `pc target -p "my-project"`. ### API key Authenticate with an [API key](/guides/projects/manage-api-keys). API keys can't access the Admin API. ```bash theme={null} pc auth configure --api-key "YOUR_API_KEY" # Or via environment variable export PINECONE_API_KEY="your-api-key" ``` API keys are scoped to a specific project. When set, control/data plane operations use the **key's project**, ignoring any [target context](/reference/cli/target-context) you've set. ## Auth priority When multiple credentials exist, the CLI chooses based on operation type. Within each credential type, environment variables take precedence over stored configuration. **Control/data plane operations:** 1. API key 2. User login token (via [managed keys](#managed-keys)) 3. Service account (via [managed keys](#managed-keys)) **Admin API operations:** 1. User login token 2. Service account User login and service account are mutually exclusive when configured via CLI commands—each clears the other. However, service account env vars don't clear a stored user login token. **Example scenarios:** * If `PINECONE_API_KEY` is set, the CLI uses it for control/data plane operations, regardless of any stored API key. * If you're logged in via `pc auth login` and also have `PINECONE_CLIENT_ID`/`PINECONE_CLIENT_SECRET` set, the user login token is used for everything—the service account env vars are ignored. * If you have an API key configured and are also logged in, the API key is used for control/data plane operations, but user login is used for Admin API operations (since API keys can't access Admin API). ## Managed keys When using user login or service account (without a default API key), the CLI automatically creates and manages API keys for control/data plane operations. This happens transparently on first use. * **Stored locally:** `~/.config/pinecone/secrets.yaml` (permissions 0600) * **Stored remotely:** Visible in console as `pinecone-cli-{id}` with origin `cli_created` ```bash theme={null} # List locally tracked managed keys pc auth local-keys list # Delete managed keys (local + remote) pc auth local-keys prune # Delete only CLI-created managed keys pc auth local-keys prune --origin cli # Delete only user-created managed keys pc auth local-keys prune --origin user # Delete a specific API key by ID pc api-key delete --id "KEY_ID" ``` When you run `pc api-key create --store` for a project that already has a CLI-created managed key, the CLI automatically deletes the old remote key before storing the new one. ## Logging out ```bash theme={null} pc auth logout ``` Clears all local auth data: tokens, credentials, API keys, managed keys, and [target context](/reference/cli/target-context). `pc auth logout` doesn't delete managed keys from Pinecone's servers. Run `pc auth local-keys prune` first for full cleanup. ## Local storage Auth data is stored in `~/.config/pinecone/` with 0600 permissions: | File | Contents | | -------------- | ---------------------------------------------------------------- | | `secrets.yaml` | OAuth token, service account credentials, API keys, managed keys | | `state.yaml` | Target org/project | | `config.yaml` | CLI settings (color, environment) | ## Check status ```bash theme={null} pc auth status ``` Shows your current authentication method, target organization and project, token expiration (for user login), and environment configuration. # CLI command reference Source: https://docs.pinecone.io/reference/cli/command-reference Complete Pinecone CLI command reference covering syntax, subcommands, flags, help output, and exit codes for auth, index, and project. This document provides a complete reference for all Pinecone CLI commands. ## Command structure The Pinecone CLI uses a hierarchical command structure. Each command consists of a primary command followed by one or more subcommands and optional flags. ```bash theme={null} pc [flags] pc [flags] ``` For example: ```bash theme={null} # Top-level command with flags pc target -o "organization-name" -p "project-name" # Command (index) and subcommand (list) pc index list # Command (index) and subcommand (create) with flags pc index create \ --name my-index \ --dimension 1536 \ --metric cosine \ --cloud aws \ --region us-east-1 # Command (auth) and nested subcommands (local-keys prune) with flags pc auth local-keys prune --id proj-abc123 --skip-confirmation ``` ## Getting help The CLI provides help for commands at every level: ```bash theme={null} # top-level help pc --help pc -h # command help pc auth --help pc index --help pc project --help # subcommmand help pc index create --help pc project create --help pc auth configure --help # nested subcommand help pc auth local-keys prune --help ``` ## Exit codes All commands return exit code `0` for success and `1` for error. ## Available commands This section describes all commands offered by the Pinecone CLI. ### Top-level commands **Description** Authenticate via a web browser. After login, set a [target org and project](/reference/cli/target-context) with `pc target` before accessing data. This command defaults to an initial organization and project to which you have access (these values display in the terminal), but you can change them with `pc target`. **Usage** ```bash theme={null} pc login ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Log in via browser pc login # Then set target context pc target -o "my-org" -p "my-project" ``` This is an alias for `pc auth login`. Both commands perform the same operation. **Description** Clears all authentication data from local storage, including: * User login token * Service account credentials (client ID and secret) * Default (manually specified) API key * Locally managed keys (for all projects) * Target organization and project context **Usage** ```bash theme={null} pc logout ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Clear all credentials and context pc logout ``` This is an alias for `pc auth logout`. Both commands perform the same operation. Does not delete managed API keys from Pinecone's servers. Run `pc auth local-keys prune` before logging out to fully clean up. **Description** Set the target organization and project for the CLI. Supports interactive organization and project selection or direct specification via flags. For details, see [CLI target context](/reference/cli/target-context). **Usage** ```bash theme={null} pc target [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------ | :--------- | :----------------------------- | | `--clear` | | Clear target context | | `--json` | `-j` | Output in JSON format | | `--org` | `-o` | Organization name | | `--organization-id` | | Organization ID | | `--project` | `-p` | Project name | | `--project-id` | | Project ID | | `--show` | `-s` | Display current target context | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Interactive targeting after login pc login pc target # Set specific organization and project pc target -o "my-org" -p "my-project" # Show current context pc target --show # Clear all context pc target --clear ``` **Description** Displays version information for the CLI, including the version number, commit SHA, and build date. **Usage** ```bash theme={null} pc version ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Display version information pc version ``` **Description** Displays information about the currently authenticated user. To use this command, you must be authenticated via user login. **Usage** ```bash theme={null} pc whoami ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc whoami ``` This is an alias for `pc auth whoami`. Both commands perform the same operation. ### Authentication **Description** Selectively clears specific authentication data without affecting other credentials. At least one flag is required. **Usage** ```bash theme={null} pc auth clear [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------ | :--------- | :-------------------------------------------------- | | `--api-key` | | Clear only the default (manually specified) API key | | `--service-account` | | Clear only service account credentials | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Clear only the default (manually specified) API key pc auth clear --api-key pc auth status # Clear service account pc auth clear --service-account ``` More surgical than `pc auth logout`. Does not clear user login token or managed keys. For those, use `pc auth logout` or `pc auth local-keys prune`. **Description** Configures service account credentials or a default (manually specified) API key. Service accounts automatically target the organization and prompt for project selection, unless there is only one project. A default API key overrides any previously specified target organization/project context. When setting a service account, this operation clears the user login token, if one exists. For details, see [CLI target context](/reference/cli/target-context). **Usage** ```bash theme={null} pc auth configure [flags] ``` **Flags** | Long flag | Short flag | Description | | :---------------------- | :--------- | :--------------------------------------------------- | | `--api-key` | | Default API key to use for authentication | | `--client-id` | | Service account client ID | | `--client-secret` | | Service account client secret | | `--client-secret-stdin` | | Read client secret from stdin | | `--json` | `-j` | Output in JSON format | | `--project-id` | `-p` | Target project ID (optional, interactive if omitted) | | `--prompt-if-missing` | | Prompt for missing credentials | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Service account setup (auto-targets org and prompts for project) pc auth configure --client-id my-id --client-secret my-secret # Service account with specific project pc auth configure \ --client-id my-id \ --client-secret my-secret \ -p proj-123 # Default API key (overrides any target context) pc auth configure --api-key pcsk_abc123 ``` `pc auth configure --api-key "YOUR_API_KEY"` does the same thing as `pc config set-api-key "YOUR_API_KEY"`. To learn about targeting a project after authenticating with a service account, see [CLI target context](/reference/cli/target-context). **Description** Displays all [managed API keys](/reference/cli/authentication#managed-keys) stored locally by the CLI, with various details. **Usage** ```bash theme={null} pc auth local-keys list [flags] ``` **Flags** | Long flag | Short flag | Description | | :--------- | :--------- | :----------------------------------------- | | `--json` | `-j` | Output in JSON format | | `--reveal` | | Show the actual API key values (sensitive) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all locally managed keys pc auth local-keys list # Show key values pc auth local-keys list --reveal # After storing a key pc api-key create -n "my-key" --store pc auth local-keys list ``` **Description** Deletes locally stored [managed API keys](/reference/cli/authentication#managed-keys) from local storage and Pinecone's servers. Filters by origin (`cli`/`user`/`all`) or project ID. **Usage** ```bash theme={null} pc auth local-keys prune [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :---------------------------------------------------------- | | `--dry-run` | | Preview deletions without applying | | `--id` | | Prune keys for specific project ID only | | `--json` | `-j` | Output in JSON format | | `--origin` | `-o` | Filter by origin - `cli`, `user`, or `all` (default: `all`) | | `--skip-confirmation` | | Skip confirmation prompt | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Preview deletions pc auth local-keys prune --dry-run # Delete CLI-created keys only pc auth local-keys prune -o cli --skip-confirmation # Delete for specific project pc auth local-keys prune --id proj-abc123 # Before/after check pc auth local-keys list pc auth local-keys prune -o cli pc auth local-keys list ``` This deletes keys from both local storage and Pinecone servers. Use `--dry-run` to preview before committing. **Description** Authenticate via user login in the web browser. After login, [set a target org and project](/reference/cli/target-context). **Usage** ```bash theme={null} pc auth login pc login # shorthand ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Login and set target pc auth login pc target -o "my-org" -p "my-project" pc index list ``` Tokens refresh automatically and remain valid for up to 120 days. If you're inactive for more than 30 days, you must re-authenticate. Logging in clears any existing service account credentials. This command does the same thing as `pc login`. **Description** Clears all authentication data from local storage, including: * User login token * Service account credentials (client ID and secret) * Default (manually specified) API key * Locally managed keys (for all projects) * Target organization and project context **Usage** ```bash theme={null} pc auth logout ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Clear all credentials and context pc auth logout ``` This command does the same thing as `pc logout`. Does not delete managed API keys from Pinecone's servers. Run `pc auth local-keys prune` before logging out to fully clean up. **Description** Shows details about all configured authentication methods. **Usage** ```bash theme={null} pc auth status [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Check status after login pc auth login pc auth status # JSON output for scripting pc auth status --json ``` **Description** Displays information about the currently authenticated user. To use this command, you must be authenticated via user login. **Usage** ```bash theme={null} pc auth whoami ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc auth whoami ``` This command does the same thing as `pc whoami`. ### Indexes **Description** Modifies the configuration of an existing index. **Usage** ```bash theme={null} pc index configure [flags] ``` **Flags** | Long flag | Short flag | Description | | :----------------------- | :--------- | :-------------------------------------------------------------- | | `--index-name` | `-i` | Name of index to configure (required) | | `--deletion-protection` | | Enable or disable deletion protection - `enabled` or `disabled` | | `--tags` | | Custom user tags (key=value pairs) | | `--json` | `-j` | Output in JSON format | | **Dedicated read nodes** | | | | `--read-mode` | | Read capacity mode - `ondemand` or `dedicated` | | `--read-node-type` | | Node type for dedicated read - `b1` or `t1` | | `--read-shards` | | Number of shards for dedicated read capacity | | `--read-replicas` | | Number of replicas for dedicated read capacity | | **Integrated embedding** | | | | `--model` | | Embedding model name | | `--field-map` | | Field mapping for embedding (key=value pairs) | | `--read-parameters` | | Read parameters for embedding model (key=value pairs) | | `--write-parameters` | | Write parameters for embedding model (key=value pairs) | | **Pods** | | | | `--pod-type` | `-t` | Type of pod to use; can only upgrade when configuring | | `--replicas` | `-r` | Number of replicas of the index to configure | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Enable deletion protection pc index configure --index-name my-index --deletion-protection enabled # Add tags pc index configure --index-name my-index --tags environment=production,team=ml # Switch to dedicated read capacity pc index configure --index-name my-index \ --read-mode dedicated \ --read-node-type b1 \ --read-shards 2 \ --read-replicas 2 # Verify changes pc index describe --index-name my-index ``` Configuration changes may take some time to take effect. **Description** Creates a new index in your Pinecone project. Supports serverless, pod-based, integrated (with embedding model), and BYOC (Bring Your Own Cloud) index types. **Usage** ```bash theme={null} pc index create [flags] ``` **Flags** | Long flag | Short flag | Description | | :----------------------- | :--------- | :----------------------------------------------------------------------------- | | `--name` | `-n` | Index name (required) | | `--dimension` | `-d` | Vector dimension (required for standard indexes, optional for integrated) | | `--metric` | `-m` | Similarity metric - `cosine`, `euclidean`, or `dotproduct` (default: `cosine`) | | `--cloud` | `-c` | Cloud provider - `aws`, `gcp`, or `azure` | | `--region` | `-r` | Cloud region | | `--vector-type` | `-v` | Vector type - `dense` or `sparse` (serverless only) | | `--source-collection` | | Name of the source collection from which to create the index | | `--schema` | | Metadata schema to control which fields are indexed (comma-separated) | | `--deletion-protection` | | Deletion protection - `enabled` or `disabled` | | `--tags` | | Custom user tags (key=value pairs) | | `--json` | `-j` | Output in JSON format | | **Integrated indexes** | | | | `--model` | | Integrated embedding model name | | `--field-map` | | Field mapping for integrated embedding (key=value pairs) | | `--read-parameters` | | Read parameters for embedding model (key=value pairs) | | `--write-parameters` | | Write parameters for embedding model (key=value pairs) | | **BYOC indexes** | | | | `--byoc-environment` | | BYOC environment to use for the index | | **Dedicated read nodes** | | | | `--read-mode` | | Read capacity mode - `ondemand` or `dedicated` (default: `ondemand`) | | `--read-node-type` | | Node type for dedicated read - `b1` or `t1` | | `--read-shards` | | Number of shards (each shard provides 250 GB storage) | | `--read-replicas` | | Number of replicas for higher throughput | | **Pod-based indexes** | | | | `--environment` | | Environment of the index to create (for example, `us-east-1-aws`) | | `--pod-type` | | Type of pod to use (for example, `p1.x1`, `s1.x2`) | | `--shards` | | Number of shards (default: `1`) | | `--replicas` | | Number of replicas (default: `1`) | | `--metadata-config` | | Comma-separated list of metadata fields to index for search | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Create serverless index pc index create -n my-index -d 1536 -m cosine -c aws -r us-east-1 # Create sparse vector index pc index create -n sparse-index -m dotproduct -c aws -r us-east-1 --vector-type sparse # With integrated embedding model pc index create \ -n my-index \ -m cosine \ -c aws \ -r us-east-1 \ --model multilingual-e5-large \ --field-map text=chunk_text # With dedicated read capacity pc index create \ -n my-index \ -d 1536 \ -m cosine \ -c aws \ -r us-east-1 \ --read-mode dedicated \ --read-node-type b1 \ --read-shards 2 \ --read-replicas 2 # With deletion protection pc index create \ -n my-index \ -d 1536 \ -m cosine \ -c aws \ -r us-west-2 \ --deletion-protection enabled # From collection pc index create \ -n my-index \ -d 1536 \ -m cosine \ -c aws \ -r eu-west-1 \ --source-collection my-collection # Create pod-based index pc index create \ -n my-index \ -d 1536 \ -m cosine \ --environment us-east-1-aws \ --pod-type p1.x1 \ --shards 1 \ --replicas 1 ``` For a list of valid regions for a serverless index, see [Create a serverless index](/guides/index-data/create-an-index). **Description** Permanently deletes an index and all its data. This operation cannot be undone. **Usage** ```bash theme={null} pc index delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :--------------------------------------------------------- | | `--index-name` | `-i` | Name of index to delete (required) | | `--skip-confirmation` | | Skip the deletion confirmation prompt | | `--json` | `-j` | Output in JSON format (also skips the confirmation prompt) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete an index (prompts for confirmation) pc index delete --index-name my-index # Skip the confirmation prompt pc index delete --index-name my-index --skip-confirmation # List before and after pc index list pc index delete --index-name test-index --skip-confirmation pc index list ``` This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. **Description** Displays detailed configuration and status information for a specific index. **Usage** ```bash theme={null} pc index describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :-------------------- | | `--index-name` | `-i` | Index name (required) | | `--json` | `-j` | Output in JSON format | The `--name`/`-n` flag is a deprecated alias for `--index-name`/`-i`. **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe an index pc index describe -i my-index # JSON output pc index describe -i my-index -j # Check newly created index pc index create -n test-index -d 1536 -m cosine -c aws -r us-east-1 pc index describe -i test-index ``` **Description** Displays statistics for an index, including total vector count and namespace breakdown. Optionally filter results with a metadata filter. **Usage** ```bash theme={null} pc index stats [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--filter` | `-f` | Metadata filter (inline JSON, `./path.json`, or `-` for stdin) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Get stats for an index pc index stats -i my-index # Get stats with a metadata filter pc index stats -i my-index --filter '{"genre":{"$eq":"rock"}}' # Filter from file pc index stats -i my-index --filter ./filter.json # JSON output pc index stats -i my-index -j ``` **Description** Displays all indexes in your current target project, including various details. **Usage** ```bash theme={null} pc index list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------------------------------------- | | `--json` | `-j` | Output in JSON format (includes full index details) | | `--wide` | `-w` | Show additional columns (host, embed, tags) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all indexes pc index list # Show additional details pc index list --wide # JSON output for scripting pc index list -j # After creating indexes pc index create -n test-1 -d 768 -m cosine -c aws -r us-east-1 pc index list ``` ### Namespaces **Description** Creates a new namespace within an index. Namespaces allow you to partition vectors within an index. **Usage** ```bash theme={null} pc index namespace create [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :-------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--name` | | Namespace name (required) | | `--schema` | | Metadata schema for the namespace (comma-separated) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Create a namespace pc index namespace create -i my-index --name tenant-a # Create with metadata schema (comma-separated list of filterable metadata fields) pc index namespace create -i my-index --name tenant-b --schema "category,brand" # JSON output pc index namespace create -i my-index --name tenant-c -j ``` **Description** Deletes a namespace and all its vectors from an index. This operation cannot be undone. **Usage** ```bash theme={null} pc index namespace delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :--------------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--name` | | Namespace name (required); use `__default__` for the default namespace | | `--skip-confirmation` | | Skip the deletion confirmation prompt | | `--json` | `-j` | Output in JSON format (also skips the confirmation prompt) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete a namespace (prompts for confirmation) pc index namespace delete -i my-index --name tenant-a # Delete the default namespace pc index namespace delete -i my-index --name __default__ # Skip the confirmation prompt pc index namespace delete -i my-index --name tenant-a --skip-confirmation ``` Deleting a namespace removes all vectors in that namespace. This operation cannot be undone. **Description** Displays detailed information about a specific namespace, including record count and schema configuration. **Usage** ```bash theme={null} pc index namespace describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :--------------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--name` | | Namespace name (required); use `__default__` for the default namespace | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe a namespace pc index namespace describe -i my-index --name tenant-a # Describe the default namespace pc index namespace describe -i my-index --name __default__ # JSON output pc index namespace describe -i my-index --name tenant-a -j ``` **Description** Lists all namespaces within an index, including vector counts. **Usage** ```bash theme={null} pc index namespace list [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :----------------------------- | | `--index-name` | `-i` | Index name (required) | | `--limit` | `-l` | Maximum number of results | | `--pagination-token` | `-p` | Pagination token for next page | | `--prefix` | | Filter namespaces by prefix | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all namespaces pc index namespace list -i my-index # Filter by prefix pc index namespace list -i my-index --prefix "tenant-" # Limit results pc index namespace list -i my-index --limit 10 # JSON output pc index namespace list -i my-index -j ``` ### Vectors **Description** Deletes vectors from an index by ID, filter, or deletes all vectors in a namespace. **Usage** ```bash theme={null} pc index vector delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :------------------------------------------------------------------------ | | `--index-name` | `-i` | Index name (required) | | `--namespace` | | Namespace to delete from (default: `__default__`) | | `--ids` | | Vector IDs to delete (inline JSON array, `./path.json`, or `-` for stdin) | | `--filter` | | Metadata filter (inline JSON, `./path.json`, or `-` for stdin) | | `--all-vectors` | | Delete all vectors in the namespace | | `--skip-confirmation` | | Skip the confirmation prompt shown for `--all-vectors` | | `--json` | `-j` | Output in JSON format (also skips the confirmation prompt) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete specific vectors pc index vector delete -i my-index --ids '["id1"]' # Delete multiple vectors (inline JSON array, or JSON array in a file) pc index vector delete -i my-index --ids '["id1", "id2"]' # Delete by filter pc index vector delete -i my-index --filter '{"genre":"classical"}' # Delete all vectors in a namespace (prompts for confirmation) pc index vector delete -i my-index --namespace old-data --all-vectors # Delete all vectors without the prompt pc index vector delete -i my-index --namespace old-data --all-vectors --skip-confirmation ``` Only `--all-vectors` prompts for confirmation. Targeted deletes with `--ids` or `--filter` proceed without a prompt. Pass `--skip-confirmation` (or `--json`) to bypass the `--all-vectors` prompt. Vector deletion is permanent and cannot be undone. **Description** Retrieves vectors by their IDs or by a metadata filter, returning the vector values and metadata. **Usage** ```bash theme={null} pc index vector fetch [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :----------------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--namespace` | | Namespace to fetch from (default: `__default__`) | | `--ids` | | Vector IDs to fetch (inline JSON array, `./path.json`, or `-` for stdin) | | `--filter` | `-f` | Metadata filter (inline JSON, `./path.json`, or `-` for stdin) | | `--limit` | `-l` | Maximum number of vectors to fetch | | `--pagination-token` | `-p` | Pagination token for next page | | `--body` | | Request body JSON (inline, `./path.json`, or `-` for stdin) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Fetch specific vectors by ID pc index vector fetch -i my-index --ids '["123","456","789"]' # Fetch from a file pc index vector fetch -i my-index --ids ./ids.json # Fetch by metadata filter pc index vector fetch -i my-index --filter '{"genre":{"$eq":"rock"}}' # Fetch from a namespace pc index vector fetch -i my-index --namespace tenant-a --ids '["doc-123"]' # JSON output pc index vector fetch -i my-index --ids '["vec1"]' -j ``` Use either `--ids` or `--filter`, not both. When using `--ids`, pagination flags are not applicable. **Description** Lists vector IDs in a namespace with optional pagination. **Usage** ```bash theme={null} pc index vector list [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :---------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--namespace` | | Namespace to list from (default: `__default__`) | | `--limit` | `-l` | Maximum number of IDs to return | | `--pagination-token` | `-p` | Pagination token for next page | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List vector IDs pc index vector list -i my-index # List from a namespace with limit pc index vector list -i my-index --namespace tenant-a --limit 50 # JSON output pc index vector list -i my-index -j ``` **Description** Queries an index for similar vectors using dense vectors, sparse vectors, or vector ID. **Usage** ```bash theme={null} pc index vector query [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :-------------------------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--namespace` | | Namespace to query (default: `__default__`) | | `--id` | | Query by vector ID | | `--vector` | `-v` | Query vector values (inline JSON array, `./path.json`, or `-` for stdin) | | `--sparse-indices` | | Sparse vector indices (inline JSON uint32 array, `./path.json`, or `-` for stdin) | | `--sparse-values` | | Sparse vector values (inline JSON array, `./path.json`, or `-` for stdin) | | `--top-k` | `-k` | Number of results to return (default: 10) | | `--filter` | `-f` | Metadata filter (inline JSON, `./path.json`, or `-` for stdin) | | `--include-values` | | Include vector values in results | | `--include-metadata` | | Include metadata in results | | `--body` | | Request body JSON (inline, `./path.json`, or `-` for stdin) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Query by vector ID pc index vector query -i my-index --id "doc-123" -k 10 --include-metadata # Query by vector values pc index vector query -i my-index --vector '[0.1, 0.2, 0.3]' -k 25 # Query with metadata filter pc index vector query -i my-index \ --vector '[0.1, 0.2, 0.3]' \ --filter '{"genre":{"$eq":"sci-fi"}}' \ --include-metadata # Query from file (file contains a JSON array that specifies the query vector) pc index vector query -i my-index --vector ./embedding.json -k 20 # Query with sparse vectors (inline) pc index vector query -i my-index \ --sparse-indices '[0, 5, 12]' \ --sparse-values '[0.5, 0.3, 0.8]' \ -k 15 # Query with sparse vectors from files # indices.json: [0, 5, 12] # values.json: [0.5, 0.3, 0.8] pc index vector query -i my-index \ --sparse-indices ./indices.json \ --sparse-values ./values.json \ -k 15 # Query from stdin (extract embedding from a document) # doc.json: {"id": "doc-123", "embedding": [0.1, 0.2, 0.3], "text": "..."} jq -c '.embedding' doc.json | pc index vector query -i my-index --vector - -k 10 ``` Use `--id`, `--vector`, or sparse vectors (`--sparse-indices` and `--sparse-values`) to specify what to query against. These options are mutually exclusive. **Description** Updates a vector's values, sparse values, or metadata by ID, or updates metadata for multiple vectors matching a filter. **Usage** ```bash theme={null} pc index vector update [flags] ``` **Flags** | Long flag | Short flag | Description | | :----------------- | :--------- | :----------------------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--namespace` | | Namespace containing the vector (default: `__default__`) | | `--id` | | Vector ID to update | | `--values` | | New vector values (inline JSON array, `./path.json`, or `-` for stdin) | | `--sparse-indices` | | New sparse indices (inline JSON uint32 array, `./path.json`, or `-` for stdin) | | `--sparse-values` | | New sparse values (inline JSON array, `./path.json`, or `-` for stdin) | | `--metadata` | | New or updated metadata (inline JSON, `./path.json`, or `-` for stdin) | | `--filter` | | Metadata filter for bulk update (inline JSON, `./path.json`, or `-` for stdin) | | `--dry-run` | | Preview how many records would be updated without applying changes | | `--body` | | Request body JSON (inline, `./path.json`, or `-` for stdin) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Update metadata for a single vector pc index vector update -i my-index --id "vec1" --metadata '{"category":"updated"}' # Update values for a single vector pc index vector update -i my-index --id "vec1" --values '[0.2, 0.3, 0.4]' # Update sparse values # indices.json: [0, 5, 12] # values.json: [0.5, 0.3, 0.8] pc index vector update -i my-index --id "vec1" \ --sparse-indices ./indices.json \ --sparse-values ./values.json # Bulk update metadata by filter (preview first) pc index vector update -i my-index \ --filter '{"genre":{"$eq":"sci-fi"}}' \ --metadata '{"genre":"fantasy"}' \ --dry-run # Apply the bulk update pc index vector update -i my-index \ --filter '{"genre":{"$eq":"sci-fi"}}' \ --metadata '{"genre":"fantasy"}' ``` Use either `--id` for single vector updates or `--filter` for bulk updates. These options are mutually exclusive. **Description** Inserts or updates vectors in an index from a JSON or JSONL file, or inline JSON. The CLI automatically batches vectors for efficient uploading. Files can contain any number of vectors—the CLI splits them into batches and sends multiple API requests as needed. **Usage** ```bash theme={null} pc index vector upsert [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :--------------------------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--namespace` | | Namespace to upsert into (default: `__default__`) | | `--body` | | Request body JSON or JSONL (inline, `./path.json[l]`, or `-` for stdin) (required) | | `--batch-size` | `-b` | Size of batches to upsert (default: 500) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Upsert from JSON file (with "vectors" array) # vectors.json: {"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]} pc index vector upsert -i my-index --body ./vectors.json # Upsert with inline JSON pc index vector upsert -i my-index --body '{"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]}' # Upsert from JSONL file (one vector per line) # vectors.jsonl: {"id": "vec1", "values": [0.1, 0.2, 0.3]} # {"id": "vec2", "values": [0.4, 0.5, 0.6]} pc index vector upsert -i my-index --body ./vectors.jsonl # Upsert from stdin (same format as JSON or JSONL file) cat vectors.json | pc index vector upsert -i my-index --body - # Custom batch size (default: 500, max: 1000 per API request) pc index vector upsert -i my-index --body ./vectors.json --batch-size 1000 ``` **Batch size limits:** The API accepts up to 1000 vectors per request. The CLI defaults to batches of 500 vectors, but you can adjust this with `--batch-size` (up to 1000). Large files are automatically split into multiple batches. **File size:** There's no explicit file size limit—the CLI reads the entire file into memory and batches it automatically. Very large files are supported as long as they fit in available system memory. ### Records **Description** Search an index namespace with a query text, query vector, or record ID and return the most similar records, along with their similarity scores. Optionally, rerank the initial results based on their relevance to the query. Searching with text is supported only for indexes with an integrated embedding configured. Searching with a query vector or record ID is supported for all indexes. Exactly one primary query mode must be provided: * `--inputs` — query text (requires an index with integrated embedding) * `--id` — use an existing record's vector as the query * `--vector` — provide a dense vector directly (all index types) * `--sparse-indices` + `--sparse-values` — sparse vector (all index types) Combine `--vector` with `--sparse-indices`/`--sparse-values` for hybrid search. Use `--body` to pass a full request object; flags take precedence over `--body` when both specify the same field. **Usage** ```bash theme={null} pc index record search [flags] ``` **Flags** | Long flag | Short flag | Description | | :----------------- | :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--index-name` | `-i` | Name of the index to search (required) | | `--inputs` | | Query inputs for text search (inline JSON, `./path.json`, or `-` for stdin); requires integrated embedding. Mutually exclusive with `--id` and `--vector`. | | `--id` | | Use an existing record's vector by ID for the query. Mutually exclusive with `--inputs` and `--vector`. | | `--vector` | `-v` | Dense vector values to search against (inline JSON float32 array, `./path.json`, or `-` for stdin). Mutually exclusive with `--inputs` and `--id`. | | `--sparse-indices` | | Sparse vector indices (inline JSON int32 array, `./path.json`, or `-` for stdin). Must be used together with `--sparse-values`. | | `--sparse-values` | | Sparse vector values (inline JSON float32 array, `./path.json`, or `-` for stdin). Must be used together with `--sparse-indices`. | | `--top-k` | `-k` | Number of results to return (required) | | `--namespace` | | Namespace to search | | `--filter` | | Metadata filter (inline JSON, `./path.json`, or `-` for stdin) | | `--rerank` | | Re-score results using an inference model (inline JSON, `./path.json`, or `-` for stdin). Required fields: `model` (string), `rank_fields` (string array). | | `--match-terms` | | Keyword terms filter for sparse integrated indexes (inline JSON, `./path.json`, or `-` for stdin). Required field: `terms` (string array). Requires `--inputs`. | | `--fields` | | Fields to return in results (inline JSON string array, `./path.json`, or `-` for stdin) | | `--body` | | Full request body JSON (inline, `./path.json`, or `-` for stdin). Flags take precedence when both specify the same field. | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Examples** ```bash theme={null} # Text search (integrated embedding indexes only) pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --top-k 10 pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --namespace my-namespace --top-k 5 pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --filter '{"category":"health"}' --top-k 10 pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --fields '["_id","chunk_text","category"]' --top-k 10 pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --rerank '{"model":"bge-reranker-v2-m3","rank_fields":["chunk_text"]}' --top-k 10 pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --match-terms '{"terms":["vaccine","prevention"]}' --top-k 10 # Search by record ID for query vector (all index types) pc index record search --index-name my-index --id rec-123 --top-k 10 # Vector search (all index types) pc index record search --index-name my-index --vector '[0.1,0.2,0.3]' --top-k 10 pc index record search --index-name my-index --sparse-indices '[1,5,9]' --sparse-values '[0.4,0.8,0.2]' --top-k 10 pc index record search --index-name my-index --vector '[0.1,0.2,0.3]' --sparse-indices '[1,5,9]' --sparse-values '[0.4,0.8,0.2]' --top-k 10 # Full request body (must include top_k in the body) pc index record search --index-name my-index --body ./search.json ``` ```text CLI theme={null} Usage: 5 (read units) ID SCORE FIELDS rec-001 0.912340 {"category":"health","chunk_text":"vaccine research..."} rec-002 0.887210 {"category":"health","chunk_text":"disease prevention..."} ``` **Description** Upsert records into an integrated index namespace from a JSON or JSONL payload. The `--body` flag accepts a JSON object containing a `"records"` array of `IntegratedRecord` objects, a raw JSON array of records, or a JSONL stream of records (one object per line). The value can be inline JSON, a path to a `.json` or `.jsonl` file, or `-` to read from stdin. Records are sent in batches. The default batch size is 96 (the API maximum). Use `--batch-size` to send smaller batches. **Usage** ```bash theme={null} pc index record upsert [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :-------------------------------------------------------------------------------------- | | `--index-name` | `-i` | Name of the index to upsert into (required) | | `--body` | | Request body JSON or JSONL (inline JSON, `./path.json[l]`, or `-` for stdin) (required) | | `--namespace` | | Namespace to upsert into | | `--batch-size` | `-b` | Number of records per batch (default: `96`, max: `96`) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Examples** ```bash theme={null} # Upsert from a JSON file pc index record upsert --index-name my-index --body ./records.json # Upsert from a JSONL file into a specific namespace pc index record upsert --index-name my-index --namespace my-namespace --body ./records.jsonl # Upsert from stdin cat records.jsonl | pc index record upsert --index-name my-index --namespace my-namespace --body - ``` ### Collections **Description** Creates a static copy of a pod-based index as a collection. Collections can be used to store a snapshot of an index's data for backup or migration purposes. **Usage** ```bash theme={null} pc index collection create [flags] ``` **Flags** | Long flag | Short flag | Description | | :--------- | :--------- | :---------------------------------------------------------- | | `--name` | `-n` | Name to give the collection (required) | | `--source` | `-s` | Name of the pod-based index to use as the source (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Create a collection from a pod-based index pc index collection create --name my-collection --source my-index ``` ```text CLI theme={null} ATTRIBUTE VALUE Name my-collection State Initializing Dimension 1536 Size 0 VectorCount 0 Environment us-east-1-aws ``` **Description** Deletes a collection permanently. This action cannot be undone. **Usage** ```bash theme={null} pc index collection delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :--------------------------------------------------------- | | `--name` | `-n` | Name of the collection to delete (required) | | `--skip-confirmation` | | Skip the deletion confirmation prompt | | `--json` | `-j` | Output in JSON format (also skips the confirmation prompt) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete a collection (prompts for confirmation) pc index collection delete --name my-collection # Skip the confirmation prompt pc index collection delete --name my-collection --skip-confirmation ``` This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. **Description** Returns detailed information about a single collection, including its state, dimension, size, vector count, and environment. **Usage** ```bash theme={null} pc index collection describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------------------------------- | | `--name` | `-n` | Name of the collection to describe (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe a collection pc index collection describe --name my-collection ``` ```text CLI theme={null} ATTRIBUTE VALUE Name my-collection State Ready Dimension 1536 Size 104857600 VectorCount 10000 Environment us-east-1-aws ``` **Description** Lists all collections in your current project, sorted alphabetically by name. **Usage** ```bash theme={null} pc index collection list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all collections pc index collection list ``` ```text CLI theme={null} NAME DIMENSION SIZE STATUS VECTORS ENVIRONMENT my-collection 1536 104857600 Ready 10000 us-east-1-aws ``` ### Backups **Description** Creates a backup of a serverless index. Backups are static copies that only consume storage. **Usage** ```bash theme={null} pc index backup create [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------- | :--------- | :------------------------------------------------------------------- | | `--index-name` | `-i` | Name of the index to back up (required) | | `--name` | | Human-readable label for the backup (the backup ID is always a UUID) | | `--description` | `-d` | Description for the backup | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Create a backup pc index backup create -i my-index # Create with name and description pc index backup create -i my-index --name "nightly-backup" -d "Nightly backup before deployment" # JSON output pc index backup create -i my-index -j ``` **Description** Permanently deletes a backup. This operation cannot be undone. **Usage** ```bash theme={null} pc index backup delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :--------------------------------------------------------- | | `--id` | `-i` | Backup ID to delete (required) | | `--skip-confirmation` | | Skip the deletion confirmation prompt | | `--json` | `-j` | Output in JSON format (also skips the confirmation prompt) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete a backup by ID (prompts for confirmation) pc index backup delete -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f # Skip the confirmation prompt pc index backup delete -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f --skip-confirmation ``` This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. Backup deletion is permanent and cannot be undone. **Description** Displays detailed information about a specific backup. **Usage** ```bash theme={null} pc index backup describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :------------------------------- | | `--id` | `-i` | Backup ID to describe (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe a backup pc index backup describe -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f # JSON output pc index backup describe -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -j ``` **Description** Lists backups in the current project, optionally filtered by index name. **Usage** ```bash theme={null} pc index backup list [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :----------------------------- | | `--index-name` | `-i` | Filter backups by index name | | `--limit` | `-l` | Maximum number of results | | `--pagination-token` | `-p` | Pagination token for next page | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all backups in the project pc index backup list # List backups for a specific index pc index backup list --index-name my-index # Limit results pc index backup list --limit 10 # JSON output pc index backup list -j ``` **Description** Creates a new index from a backup. **Usage** ```bash theme={null} pc index restore [flags] ``` **Flags** | Long flag | Short flag | Description | | :---------------------- | :--------- | :--------------------------------------------------- | | `--id` | `-i` | Backup ID (UUID) to restore from (required) | | `--name` | `-n` | Name for the new index (required) | | `--deletion-protection` | | Enable deletion protection - `enabled` or `disabled` | | `--tags` | `-t` | Tags to apply to the new index (key=value pairs) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Restore an index from a backup pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index # Restore with tags and deletion protection pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index \ --tags env=prod,team=search \ --deletion-protection enabled # JSON output pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index -j ``` **Description** Displays the status and details of a restore job. **Usage** ```bash theme={null} pc index restore describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :------------------------------------ | | `--id` | `-i` | Restore job ID to describe (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe a restore job pc index restore describe -i rj-abc123 # JSON output pc index restore describe -i rj-abc123 -j ``` **Description** Lists all restore jobs in the current project. **Usage** ```bash theme={null} pc index restore list [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :----------------------------- | | `--limit` | `-l` | Maximum number of results | | `--pagination-token` | `-p` | Pagination token for next page | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List restore jobs pc index restore list # Limit results pc index restore list --limit 10 # JSON output pc index restore list -j ``` ### Imports **Description** Start an import that loads vector data from a storage provider into a serverless index. The URI must begin with the scheme of a supported provider (for example, `s3://`). For private buckets, configure a storage integration in the Pinecone console and pass the integration ID with `--integration-id`. Use `--error-mode` to control behavior when records fail: `continue` skips failing records and keeps going; `abort` stops the import on first error. Defaults to `continue`. **Usage** ```bash theme={null} pc index import start [flags] ``` **Flags** | Long flag | Short flag | Description | | :----------------- | :--------- | :-------------------------------------------------------------------- | | `--index-name` | `-i` | Name of the index to import into (required) | | `--uri` | `-u` | URI of the data to import, for example `s3://bucket/path/` (required) | | `--integration-id` | | Storage integration ID for private buckets | | `--error-mode` | | How to handle record errors: `continue` (default) or `abort` | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Examples** ```bash theme={null} # Start an import from a public S3 bucket pc index import start --index-name my-index --uri s3://my-bucket/data/ # Start an import from a private bucket using a storage integration pc index import start --index-name my-index --uri s3://my-bucket/data/ --integration-id intg-123 # Abort on the first error instead of continuing pc index import start --index-name my-index --uri s3://my-bucket/data/ --error-mode abort # JSON output pc index import start --index-name my-index --uri s3://my-bucket/data/ -j ``` ```text CLI theme={null} Import imp-abc123 started. ATTRIBUTE VALUE Import ID imp-abc123 ``` **Description** Show the current status and details of an import operation, including percent complete, records imported, and any error messages. **Usage** ```bash theme={null} pc index import describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :------------------------------------------------- | | `--index-name` | `-i` | Name of the index the import belongs to (required) | | `--id` | | ID of the import to describe (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe an import operation pc index import describe --index-name my-index --id import-123 # JSON output pc index import describe --index-name my-index --id import-123 -j ``` ```text CLI theme={null} ATTRIBUTE VALUE Import ID import-123 Status InProgress URI s3://my-bucket/data/ Percent Complete 45.0% Records Imported 450 Created At 2024-01-15 12:00:00 Finished At - Error None ``` **Description** List bulk import operations for the given index, with optional pagination. **Usage** ```bash theme={null} pc index import list [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :-------------------------------------------------------- | | `--index-name` | `-i` | Name of the index to list imports for (required) | | `--limit` | `-l` | Maximum number of imports to return | | `--pagination-token` | `-p` | Pagination token to continue a previous listing operation | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Examples** ```bash theme={null} # List all imports for an index pc index import list --index-name my-index # List imports with a page size limit pc index import list --index-name my-index --limit 10 # Continue paginating from a previous call pc index import list --index-name my-index --pagination-token eyJ... # JSON output pc index import list --index-name my-index -j ``` ```text CLI theme={null} IMPORT ID STATUS URI PERCENT RECORDS CREATED FINISHED imp-abc123 Completed s3://my-bucket/data/ 100.0% 1000 2024-01-15 12:00:00 2024-01-15 12:05:00 imp-def456 InProgress s3://other-bucket/data/ 45.0% 450 2024-01-15 13:00:00 - ``` **Description** Cancel an import operation that is currently pending or in progress. Already-completed or failed imports cannot be canceled. **Usage** ```bash theme={null} pc index import cancel [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :------------------------------------------------- | | `--index-name` | `-i` | Name of the index the import belongs to (required) | | `--id` | | ID of the import to cancel (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Cancel an import operation pc index import cancel --index-name my-index --id import-123 # JSON output pc index import cancel --index-name my-index --id import-123 -j ``` ```text CLI theme={null} Import import-123 canceled. ``` ### Projects **Description** Creates a new project in your [target organization](/reference/cli/target-context), using the specified configuration. **Usage** ```bash theme={null} pc project create [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :------------------------------------------------------------- | | `--force-encryption` | | Enable encryption with CMEK | | `--json` | `-j` | Output in JSON format | | `--name` | `-n` | Project name (required) | | `--target` | | Automatically target the project in the CLI after it's created | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Basic project creation pc project create -n "demo-project" ``` **Description** Permanently deletes a project and all its resources. This operation cannot be undone. **Usage** ```bash theme={null} pc project delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :---------------------------------------------------------- | | `--id` | `-i` | Project ID (optional, uses target project if not specified) | | `--json` | `-j` | Output in JSON format | | `--skip-confirmation` | | Skip confirmation prompt | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete target project pc project delete # Delete specific project pc project delete -i proj-abc123 # Skip confirmation pc project delete -i proj-abc123 --skip-confirmation ``` Must delete all indexes and collections in the project first. If the deleted project is your current target, set a new target after deleting it. **Description** Displays detailed information about a specific project, including various details. **Usage** ```bash theme={null} pc project describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--id` | `-i` | Project ID (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe a project pc project describe -i proj-abc123 # JSON output pc project describe -i proj-abc123 --json # Find ID and describe pc project list pc project describe -i proj-abc123 ``` **Description** Displays all projects in your [target organization](/reference/cli/target-context), including various details. **Usage** ```bash theme={null} pc project list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all projects pc project list # JSON output pc project list --json # List after login pc auth login pc auth target -o "my-org" pc project list ``` **Description** Modifies the configuration of the [target project](/reference/cli/target-context), or a specific project ID. **Usage** ```bash theme={null} pc project update [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :---------------------------------- | | `--force-encryption` | `-f` | Enable/disable encryption with CMEK | | `--id` | `-i` | Project ID (required) | | `--json` | `-j` | Output in JSON format | | `--name` | `-n` | New project name | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Update name pc project update -i proj-abc123 -n "new-name" ``` ### Organizations **Description** Permanently deletes an organization and all its resources. This operation cannot be undone. **Usage** ```bash theme={null} pc organization delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :------------------------- | | `--id` | `-i` | Organization ID (required) | | `--json` | `-j` | Output in JSON format | | `--skip-confirmation` | | Skip confirmation prompt | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete an organization pc organization delete -i org-abc123 # Skip confirmation pc organization delete -i org-abc123 --skip-confirmation ``` This is a highly destructive action. Deletion is permanent. If the deleted organization is your current [target](/reference/cli/target-context), set a new target after deleting. **Description** Displays detailed information about a specific organization, including name, ID, creation date, payment status, plan, and support tier. **Usage** ```bash theme={null} pc organization describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :------------------------- | | `--id` | `-i` | Organization ID (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe an organization pc organization describe -i org-abc123 # JSON output pc organization describe -i org-abc123 --json # Find ID and describe pc organization list pc organization describe -i org-abc123 ``` **Description** Displays all organizations that the authenticated user has access to, including name, ID, creation date, payment status, plan, and support tier. **Usage** ```bash theme={null} pc organization list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all organizations pc organization list # JSON output pc organization list --json # List after login pc auth login pc organization list ``` **Description** Modifies the configuration of the [target organization](/reference/cli/target-context), or a specific organization ID. **Usage** ```bash theme={null} pc organization update [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :------------------------- | | `--id` | `-i` | Organization ID (required) | | `--json` | `-j` | Output in JSON format | | `--name` | `-n` | New organization name | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Update name pc organization update -i org-abc123 -n "new-name" # Verify changes pc organization update -i org-abc123 -n "Acme Corp" pc organization describe -i org-abc123 ``` ### API keys **Description** Creates a new API key for the current [target project](/reference/cli/target-context) or a specific project ID. Optionally stores the key locally for CLI use. **Usage** ```bash theme={null} pc api-key create [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------------------------------------------------------------------------- | | `--id` | `-i` | Project ID (optional, uses target project if not specified) | | `--json` | `-j` | Output in JSON format | | `--name` | `-n` | Key name (required) | | `--roles` | | Roles to assign (default: `ProjectEditor`) | | `--store` | | Store the key locally for CLI use (automatically replaces any existing CLI-managed key) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Basic key creation pc api-key create -n "my-key" # Create and store locally pc api-key create -n "my-key" --store # Create with specific role pc api-key create -n "my-key" --store --roles ProjectEditor # Create for specific project pc api-key create -n "my-key" -i proj-abc123 ``` API keys are scoped to a specific organization and project. **Description** Permanently deletes an API key. Applications using this key immediately lose access. **Usage** ```bash theme={null} pc api-key delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :----------------------- | | `--id` | `-i` | API key ID (required) | | `--skip-confirmation` | | Skip confirmation prompt | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete an API key pc api-key delete -i key-abc123 # Skip confirmation pc api-key delete -i key-abc123 --skip-confirmation # Delete and clean up local storage pc api-key delete -i key-abc123 pc auth local-keys prune --skip-confirmation ``` Deletion is permanent. Applications using this key immediately lose access to Pinecone. **Description** Displays detailed information about a specific API key, including its name, ID, project ID, and roles. **Usage** ```bash theme={null} pc api-key describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--id` | `-i` | API key ID (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe an API key pc api-key describe -i key-abc123 # JSON output pc api-key describe -i key-abc123 --json # Find ID and describe pc api-key list pc api-key describe -i key-abc123 ``` Does not display the actual key value. **Description** Displays a list of all of the [target project's](/reference/cli/target-context) API keys, as found in Pinecone (regardless of whether they are stored locally by the CLI). Displays various details about each key, including name, ID, project ID, and roles. **Usage** ```bash theme={null} pc api-key list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :---------------------------------------------------------- | | `--id` | `-i` | Project ID (optional, uses target project if not specified) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List keys for target project pc api-key list # List for specific project pc api-key list -i proj-abc123 # JSON output pc api-key list --json ``` Does not display key values. **Description** Updates the name and roles of an API key. **Usage** ```bash theme={null} pc api-key update [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--id` | `-i` | API key ID (required) | | `--json` | `-j` | Output in JSON format | | `--name` | `-n` | New key name | | `--roles` | `-r` | Roles to assign | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Update name pc api-key update -i key-abc123 -n "new-name" # Update roles pc api-key update -i key-abc123 -r ProjectEditor # Verify changes pc api-key update -i key-abc123 -n "production-key" pc api-key describe -i key-abc123 ``` Cannot change the actual key. If you need a different key, create a new one. ### Config **Description** Lists all CLI configuration settings and their current values. Sensitive values like `api-key` are masked by default; use `--reveal` to see the full value. Hidden settings such as `environment` are included when `--all` is passed. **Usage** ```bash theme={null} pc config list [flags] ``` **Flags** | Long flag | Short flag | Description | | :--------- | :--------- | :-------------------------------------------------------- | | `--reveal` | | Reveal the full value for sensitive settings like api-key | | `--json` | `-j` | Output in JSON format | | `--all` | | Include hidden settings such as environment | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc config list pc config list --all pc config list --reveal pc config list --json ``` ```text CLI theme={null} KEY VALUE ENV VAR NAME ENV VAR OVERRIDE DESCRIPTION api-key ****abcd**** PINECONE_API_KEY false Default API key for authenticating with Pinecone color true Enable colored output ``` **Description** Gets the current value of a configuration setting. Valid keys are: `api-key`, `color`, `environment`. Sensitive values like `api-key` are masked by default; use `--reveal` to see the full value. **Usage** ```bash theme={null} pc config get [flags] ``` **Flags** | Long flag | Short flag | Description | | :--------- | :--------- | :-------------------------------------------------------- | | `--reveal` | | Reveal the full value for sensitive settings like api-key | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc config get api-key pc config get api-key --reveal pc config get environment pc config get color ``` **Description** Displays detailed information about a specific CLI configuration setting, including its current value, whether an environment variable is overriding it, and valid values. Valid keys are: `api-key`, `color`, `environment`. **Usage** ```bash theme={null} pc config describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :--------- | :--------- | :-------------------------------------------------------- | | `--reveal` | | Reveal the full value for sensitive settings like api-key | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc config describe api-key pc config describe color pc config describe color --json ``` ```text CLI theme={null} KEY api-key VALUE ****abcd**** ENV VAR NAME $PINECONE_API_KEY ENV VAR OVERRIDE false SENSITIVE true DESCRIPTION Default API key for authenticating with Pinecone ``` **Description** Sets a CLI configuration value. Valid keys are: `api-key`, `color`, `environment`. The value is persisted to the local config file. **Usage** ```bash theme={null} pc config set [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc config set api-key pcsk_... pc config set environment staging pc config set color false ``` **Description** Resets a CLI configuration value to its default. Valid keys are: `api-key`, `color`, `environment`. **Usage** ```bash theme={null} pc config unset [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc config unset api-key pc config unset color ``` # CLI quickstart Source: https://docs.pinecone.io/reference/cli/quickstart Pinecone CLI quickstart for installing pc, authenticating, and managing indexes, vectors, and data imports directly from your terminal. The Pinecone CLI (`pc`) lets you manage Pinecone resources directly from your terminal. ## Install ```bash theme={null} brew tap pinecone-io/tap brew install pinecone-io/tap/pinecone ``` Pre-built binaries for macOS, Linux, and Windows are available on the [GitHub Releases page](https://github.com/pinecone-io/cli/releases). | Platform | Architectures | | :------- | :------------------------------------- | | macOS | Intel (x86\_64), Apple Silicon (ARM64) | | Linux | x86\_64, ARM64, i386 | | Windows | x86\_64, i386 | ## Authenticate ```bash theme={null} pc auth login ``` Visit the URL in your terminal to sign in. The CLI automatically sets your default organization and project. To target a different org/project: ```bash theme={null} pc target -o "my-org" -p "my-project" ``` For CI/CD or automation, you can also authenticate with a [service account](/reference/cli/authentication#service-account) or [API key](/reference/cli/authentication#api-key). ## Manage indexes ```bash theme={null} # List indexes pc index list # Create an index pc index create -n my-index -d 3 -m cosine -c aws -r us-east-1 # Get index details pc index describe -i my-index # Get index statistics pc index stats -i my-index ``` ## Work with vectors ```bash theme={null} # Upsert vectors (from file or inline JSON) pc index vector upsert -i my-index \ --body '{"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]}' # Import from a large dataset in object storage (S3, GCS, Azure) pc index import start -i my-index --uri s3://my-bucket/data/ # Check the progress of an import operation pc index import list --i my-index pc index import describe --i my-index --id import-123 # Query (vector can be inline or in a file) pc index vector query -i my-index \ --vector '[0.1, 0.2, 0.3]' \ --top-k 10 \ --include-metadata # Fetch by ID (from file or inline JSON) pc index vector fetch -i my-index --ids '["vec1","vec2"]' # List vector IDs from an index pc index vector list -i my-index ``` ## Manage namespaces ```bash theme={null} # List namespaces pc index namespace list -i my-index # Create a namespace pc index namespace create -i my-index --name tenant-a # Delete a namespace pc index namespace delete -i my-index --name tenant-a ``` ## Back up and restore ```bash theme={null} # Create a backup pc index backup create -i my-index --name "my-index-backup" # List backups (show index, backup name, backup ID, etc.) pc index backup list -i my-index # Restore from backup (by ID, not name) pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index ``` ## JSON output Add `-j` to any command for JSON output: ```bash theme={null} pc index list -j pc index describe -i my-index -j ``` ## Getting help Use `-h` or `--help` with any command to see available options: ```bash theme={null} pc -h pc index -h pc index create -h ``` ## Next steps * [Command reference](/reference/cli/command-reference) — Full list of commands and flags * [Authentication](/reference/cli/authentication) — Service accounts, API keys, and auth priority * [Target context](/reference/cli/target-context) — How org/project targeting works # CLI target context Source: https://docs.pinecone.io/reference/cli/target-context Pinecone CLI: The CLI's **target context** determines which organization and project your commands operate on. You must authenticate before setting target. The CLI's **target context** determines which organization and project your commands operate on. You must [authenticate](/reference/cli/authentication) before setting target context. ## Flags | Flag | Short | Default | Description | | ------------------- | ----- | ------- | --------------------------------------------------------------------------------- | | `--org` | `-o` | — | Target organization by name. Mutually exclusive with `--organization-id`. | | `--organization-id` | — | — | Target organization by ID. Mutually exclusive with `--org`. | | `--project` | `-p` | — | Target project by name. Mutually exclusive with `--project-id`. | | `--project-id` | — | — | Target project by ID. Mutually exclusive with `--project`. | | `--show` | `-s` | `false` | Show the current target context. | | `--clear` | — | `false` | Clear the stored target context. | | `--json` | `-j` | `false` | Output as JSON. In non-TTY environments (CI/CD, pipes), JSON output is automatic. | `--org` and `--organization-id` are mutually exclusive — use one or the other. The same applies to `--project` and `--project-id`. ## How operations use target context | Operation type | Scope | | -------------------------------- | ---------------------------------------- | | Control plane (indexes, backups) | Target project | | Data plane (vectors, namespaces) | Target project + specified index | | Admin API (organizations) | No target context needed | | Admin API (projects) | Target organization | | Admin API (API keys) | Target project (unless `--id` specified) | ## Target context by auth method ### User login After `pc auth login`, the CLI auto-targets your default organization and its first project. ```bash theme={null} # Change target pc target -o "my-org" -p "my-project" ``` ### Service account **Via CLI command:** After `pc auth configure --client-id --client-secret`, the CLI auto-targets the service account's organization. For the project: * If one project exists, it's auto-targeted * If multiple exist, you're prompted (or use `--project-id`) * If none exist, create one and target it manually **Via environment variables:** If using `PINECONE_CLIENT_ID` and `PINECONE_CLIENT_SECRET` without running `pc auth configure`, no target context is set automatically. Run `pc target` to set it. ```bash theme={null} # Change project (org is fixed to the service account's org) pc target -p "my-project" # Or select interactively pc target ``` ### API key When using an API key, control plane and data plane operations use the **key's org/project scope**, not the CLI's stored target context. The `pc target --show` output does not reflect what these operations actually use. API keys are scoped to a specific org and project and cannot access resources outside that scope. Admin API operations still use your user login or service account credentials (API keys can't authenticate Admin API calls). ## Managing target context ```bash theme={null} pc target --show # View current target pc target --clear # Clear target context ``` ### JSON mode and non-TTY environments Running `pc target --json` with no targeting flags returns the current target context as a JSON object. This is a local-state read — **no authentication is required**: ```bash theme={null} pc target --json ``` In non-TTY environments (CI/CD pipelines, shell pipes, scripts), JSON output is automatic — the same as passing `--json` explicitly. You do not need to add the flag in automation contexts. Use `--organization-id` and `--project-id` (instead of name flags) to set context reliably in scripts, since IDs are stable and unaffected by renames: ```bash theme={null} pc target --organization-id "org-abc123" --project-id "proj-xyz789" --json ``` # Pinecone SDKs overview Source: https://docs.pinecone.io/reference/pinecone-sdks Browse official Pinecone SDKs for Python, Node.js, Java, and Go, including the version mappings between SDK releases and API versions. ## Pinecone SDKs Official Pinecone SDKs provide convenient access to the [Pinecone APIs](/reference/api/introduction). ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and SDK versions are as follows: | | `2026-04` | `2025-10` | `2025-04` | `2025-01` | `2024-10` | `2024-07` | `2024-04` | | --------------------------------------------- | :---------- | :-------- | :-------- | :-------- | :-------- | :------------ | :-------- | | [Python SDK](/reference/sdks/python/overview) | v9.x | v8.x | v7.x | v6.x | v5.3.x | v5.0.x-v5.2.x | v4.x | | [Node.js SDK](/reference/sdks/node/overview) | v8.x | v7.x | v6.x | v5.x | v4.x | v3.x | v2.x | | [Java SDK](/reference/sdks/java/overview) | Coming soon | v6.x | v5.x | v4.x | v3.x | v2.x | v1.x | | [Go SDK](/reference/sdks/go/overview) | v6.x | v5.x | v4.x | v3.x | v2.x | v1.x | v0.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. The Java SDK targeting API version `2026-04` will be available soon. ## Limitations While Pinecone tracks read unit usage with decimal precision, the Pinecone API and SDKs round these values up to the nearest whole number in query, fetch, and list responses. For example, if a query uses 0.45 read units, the API and SDKs will report it as 1 read unit. For precise read unit reporting, see [index-level metrics](/guides/production/monitoring) or the organization-wide [Usage dashboard](/guides/manage-cost/monitor-usage-and-costs#monitor-organization-level-usage-and-costs). ## Community SDKs Find community-contributed SDKs for Pinecone. These libraries are not supported by Pinecone. * [Ruby SDK](https://github.com/ScotterC/pinecone) (contributed by [ScotterC](https://github.com/ScotterC)) * [Scala SDK](https://github.com/cequence-io/pinecone-scala) (contributed by [cequence-io](https://github.com/cequence-io)) * [PHP SDK](https://github.com/probots-io/pinecone-php) (contributed by [protobots-io](https://github.com/probots-io)) # Pinecone Go SDK Source: https://docs.pinecone.io/reference/sdks/go/overview Install and use the Pinecone Go SDK to manage indexes and namespaces, upsert vectors, run semantic search, and call the Admin and Inference APIs from Go. For installation instructions and usage examples, see the [Go SDK documentation](https://github.com/pinecone-io/go-pinecone). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/go-pinecone/issues). ## Requirements The Pinecone Go SDK requires a Go version with [modules](https://go.dev/wiki/Modules) support. ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and Go SDK versions are as follows: | API version | SDK version | | :---------- | :---------- | | `2026-04` | v6.x | | `2025-10` | v5.x | | `2025-04` | v4.x | | `2025-01` | v3.x | | `2024-10` | v2.x | | `2024-07` | v1.x | | `2024-04` | v0.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. ## Install To install the latest version of the [Go SDK](https://github.com/pinecone-io/go-pinecone), add a dependency to the current module: ```shell theme={null} go get github.com/pinecone-io/go-pinecone/v6/pinecone ``` To install a specific version of the Go SDK, run the following command: ```shell theme={null} go get github.com/pinecone-io/go-pinecone/v6/pinecone@ ``` To check your SDK version, run the following command: ```shell theme={null} go list -u -m all | grep go-pinecone ``` ## Upgrade Before upgrading to `v3.0.0` or later, update all relevant code to account for the breaking changes explained [here](/release-notes/2025#2025-02-07-4). Each major version carries its version number in the module path, so crossing a major requires updating the import path in every file that uses the SDK. For example, moving from `v4` to `v6` means changing: ```go theme={null} // before import "github.com/pinecone-io/go-pinecone/v4/pinecone" // after import "github.com/pinecone-io/go-pinecone/v6/pinecone" ``` Apart from the module path, `v5.0.0` and `v6.0.0` are backward compatible with the release lines before them. If you already have the Go SDK, upgrade to the latest version as follows: ```shell theme={null} go get -u github.com/pinecone-io/go-pinecone/v6/pinecone@latest ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance: ```Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) 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 manage organizations, projects, API keys, and [role-based access control](/guides/production/manage-rbac), initialize an `AdminClient` with [service account](/guides/organizations/manage-service-accounts) credentials instead: ```Go theme={null} package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } } ``` # Reference Source: https://docs.pinecone.io/reference/sdks/go/reference Reference documentation for the Pinecone Go SDK, including client setup, types, and methods for managing indexes and vector data operations. # OpenTelemetry support Source: https://docs.pinecone.io/reference/sdks/java/open-telemetry Monitor Pinecone Java SDK operations with OpenTelemetry metrics for client latency, server processing time, and errors via Prometheus. The Pinecone Java SDK provides built-in support for capturing per-operation response metadata, making it straightforward to monitor your Pinecone usage with [OpenTelemetry](https://opentelemetry.io/) or any other observability system. With this feature, you can track client-side latency, server processing time, network overhead, error rates, and more for every data plane operation your application makes. ## How it all fits together The SDK's observability support is designed to be flexible. You don't need to adopt the entire observability stack at once -- start simple and add layers as your needs grow. Here are the components involved and how they relate to each other: * **Pinecone Java SDK**: Exposes a `ResponseMetadataListener` callback, a plain Java interface with no external dependencies. At its simplest, you can log the metadata to the console. No additional tools required. * **[OpenTelemetry](https://opentelemetry.io/) (OTel)**: An open standard and SDK for producing structured telemetry data (metrics, traces, logs). If you want standardized metrics that follow [semantic conventions](https://opentelemetry.io/docs/specs/semconv/database/database-spans/), you add the OTel SDK and wire it to the listener. This is optional. * **OTel Collector**: A vendor-neutral service that receives telemetry from your app and forwards it to a storage backend. Optional -- many setups export directly from the app to a backend. * **Prometheus**: A time-series database that stores metrics, making them queryable over time. One popular storage option. * **Grafana**: A visualization and dashboarding tool that queries Prometheus (or other backends) and displays charts and alerts. One popular visualization option. A common setup chains these together: ``` Your App (OTel SDK) → OTel Collector → Prometheus (storage) → Grafana (visualization) ``` This is just one example pipeline. You can substitute Datadog, New Relic, or any OTel-compatible backend. You can also skip OTel entirely and use [Micrometer](#example-micrometerprometheus), custom logging, or any approach that suits your stack. ## Response metadata listener The Java SDK captures response metadata through a `ResponseMetadataListener` -- a functional interface you provide when building the Pinecone client. The listener is called after each data plane operation completes (whether it succeeds or fails), and receives a `ResponseMetadata` object containing timing, status, and context information. The SDK itself has no OpenTelemetry dependency. You bring your own observability library and decide what to do with the metadata. ### Supported operations The following data plane operations are instrumented, for both synchronous (`Index`) and asynchronous (`AsyncIndex`) usage: | Operation | Description | | --------- | -------------------------- | | `upsert` | Insert or update vectors | | `query` | Search for similar vectors | | `fetch` | Retrieve vectors by ID | | `update` | Update vector metadata | | `delete` | Delete vectors | ### Available metadata Each `ResponseMetadata` object provides the following fields: | Method | Description | OTel attribute | | ------------------------ | -------------------------------------------------- | ------------------------- | | `getOperationName()` | Operation type (e.g., `upsert`, `query`) | `db.operation.name` | | `getIndexName()` | Pinecone index name | `pinecone.index_name` | | `getNamespace()` | Namespace (empty string if default) | `db.namespace` | | `getServerAddress()` | Pinecone server host | `server.address` | | `getClientDurationMs()` | Total round-trip time in ms (always available) | -- | | `getServerDurationMs()` | Server processing time in ms (may be `null`) | -- | | `getNetworkOverheadMs()` | Client minus server duration in ms (may be `null`) | -- | | `getStatus()` | `"success"` or `"error"` | `status` | | `getGrpcStatusCode()` | Raw gRPC status code (e.g., `OK`, `UNAVAILABLE`) | `db.response.status_code` | | `getErrorType()` | Error category, or `null` if successful | `error.type` | Possible `errorType` values: `validation`, `connection`, `server`, `rate_limit`, `timeout`, `auth`, `not_found`, `unknown`. ### Recommended metrics If you're recording OTel metrics, the SDK example project uses these metric names, which follow [OTel semantic conventions for database clients](https://opentelemetry.io/docs/specs/semconv/database/database-spans/): | Metric | Type | Unit | Description | | ------------------------------------- | --------- | ---- | ------------------------------- | | `db.client.operation.duration` | Histogram | ms | Client-measured round-trip time | | `pinecone.server.processing.duration` | Histogram | ms | Server processing time | | `db.client.operation.count` | Counter | -- | Total number of operations | ## Quick start: Simple logging The simplest way to use the listener is to log the metadata directly. This requires no additional dependencies beyond the Pinecone SDK: ```java theme={null} import io.pinecone.clients.Pinecone; Pinecone client = new Pinecone.Builder("PINECONE_API_KEY") .withResponseMetadataListener(metadata -> { System.out.printf("Operation: %s | Client: %dms | Server: %sms | Network: %sms | Status: %s%n", metadata.getOperationName(), metadata.getClientDurationMs(), metadata.getServerDurationMs(), metadata.getNetworkOverheadMs(), metadata.getStatus()); }) .build(); ``` Once configured, every data plane operation automatically triggers the listener: ```java theme={null} Index index = client.getIndexConnection("my-index"); index.upsert("id-1", Arrays.asList(0.1f, 0.2f, 0.3f)); // Output: Operation: upsert | Client: 47ms | Server: 40ms | Network: 7ms | Status: success ``` ## Quick start: OpenTelemetry integration To record structured metrics with OpenTelemetry, add the OTel SDK dependencies and wire a metrics recorder to the listener. ### 1. Add dependencies Add the following to your `pom.xml`: ```xml theme={null} io.pinecone pinecone-client LATEST io.opentelemetry opentelemetry-sdk io.opentelemetry opentelemetry-sdk-metrics io.opentelemetry opentelemetry-exporter-otlp io.opentelemetry opentelemetry-bom 1.35.0 pom import ``` ### 2. Create a metrics recorder The SDK's [example project](https://github.com/pinecone-io/pinecone-java-client/tree/main/examples/java-otel-metrics) includes a reusable `PineconeMetricsRecorder` class you can copy into your project. It implements `ResponseMetadataListener` and records all three recommended metrics with proper OTel attributes: ```java theme={null} import io.opentelemetry.api.common.AttributeKey; import io.opentelemetry.api.common.Attributes; import io.opentelemetry.api.common.AttributesBuilder; import io.opentelemetry.api.metrics.LongCounter; import io.opentelemetry.api.metrics.LongHistogram; import io.opentelemetry.api.metrics.Meter; import io.pinecone.configs.ResponseMetadata; import io.pinecone.configs.ResponseMetadataListener; public class PineconeMetricsRecorder implements ResponseMetadataListener { private static final AttributeKey DB_SYSTEM = AttributeKey.stringKey("db.system"); private static final AttributeKey DB_OPERATION_NAME = AttributeKey.stringKey("db.operation.name"); private static final AttributeKey DB_NAMESPACE = AttributeKey.stringKey("db.namespace"); private static final AttributeKey PINECONE_INDEX_NAME = AttributeKey.stringKey("pinecone.index_name"); private static final AttributeKey SERVER_ADDRESS = AttributeKey.stringKey("server.address"); private static final AttributeKey STATUS = AttributeKey.stringKey("status"); private static final AttributeKey ERROR_TYPE = AttributeKey.stringKey("error.type"); private final LongHistogram clientDurationHistogram; private final LongHistogram serverDurationHistogram; private final LongCounter operationCounter; public PineconeMetricsRecorder(Meter meter) { this.clientDurationHistogram = meter.histogramBuilder("db.client.operation.duration") .setDescription("Duration of Pinecone operations from client perspective") .setUnit("ms") .ofLongs() .build(); this.serverDurationHistogram = meter.histogramBuilder("pinecone.server.processing.duration") .setDescription("Server processing time from x-pinecone-response-duration-ms header") .setUnit("ms") .ofLongs() .build(); this.operationCounter = meter.counterBuilder("db.client.operation.count") .setDescription("Total number of Pinecone operations") .setUnit("{operation}") .build(); } @Override public void onResponse(ResponseMetadata metadata) { AttributesBuilder attributesBuilder = Attributes.builder() .put(DB_SYSTEM, "pinecone") .put(DB_OPERATION_NAME, metadata.getOperationName()) .put(PINECONE_INDEX_NAME, metadata.getIndexName()) .put(SERVER_ADDRESS, metadata.getServerAddress()) .put(STATUS, metadata.getStatus()); String namespace = metadata.getNamespace(); if (namespace != null && !namespace.isEmpty()) { attributesBuilder.put(DB_NAMESPACE, namespace); } if (!metadata.isSuccess() && metadata.getErrorType() != null) { attributesBuilder.put(ERROR_TYPE, metadata.getErrorType()); } Attributes attributes = attributesBuilder.build(); clientDurationHistogram.record(metadata.getClientDurationMs(), attributes); Long serverDuration = metadata.getServerDurationMs(); if (serverDuration != null) { serverDurationHistogram.record(serverDuration, attributes); } operationCounter.add(1, attributes); } } ``` ### 3. Wire it into the Pinecone client Initialize the OTel SDK, create the recorder, and pass it to the Pinecone client builder: ```java theme={null} import io.opentelemetry.api.metrics.Meter; import io.opentelemetry.sdk.OpenTelemetrySdk; import io.opentelemetry.sdk.metrics.SdkMeterProvider; import io.opentelemetry.sdk.metrics.export.PeriodicMetricReader; import io.opentelemetry.exporter.otlp.metrics.OtlpGrpcMetricExporter; import io.pinecone.clients.Pinecone; // Set up OTel with OTLP exporter OtlpGrpcMetricExporter exporter = OtlpGrpcMetricExporter.builder() .setEndpoint("http://localhost:4317") .build(); SdkMeterProvider meterProvider = SdkMeterProvider.builder() .registerMetricReader(PeriodicMetricReader.builder(exporter).build()) .build(); OpenTelemetrySdk openTelemetry = OpenTelemetrySdk.builder() .setMeterProvider(meterProvider) .build(); // Create the metrics recorder Meter meter = openTelemetry.getMeter("pinecone.client"); PineconeMetricsRecorder recorder = new PineconeMetricsRecorder(meter); // Build the Pinecone client with the recorder Pinecone client = new Pinecone.Builder("PINECONE_API_KEY") .withResponseMetadataListener(recorder) .build(); // Use the client normally -- metrics are recorded automatically Index index = client.getIndexConnection("my-index"); index.upsert("id-1", Arrays.asList(0.1f, 0.2f, 0.3f)); index.query(3, Arrays.asList(0.1f, 0.2f, 0.3f)); ``` For a complete runnable example with Docker Compose, Prometheus, and Grafana, see the [java-otel-metrics example project](https://github.com/pinecone-io/pinecone-java-client/tree/main/examples/java-otel-metrics) in the SDK repository. ## Example: Micrometer/Prometheus If your application uses [Micrometer](https://micrometer.io/) (common in Spring Boot), you can wire the listener to Micrometer instead of the OTel SDK: ```java theme={null} import io.micrometer.core.instrument.MeterRegistry; import io.micrometer.core.instrument.Timer; import io.pinecone.clients.Pinecone; import java.util.concurrent.TimeUnit; Pinecone client = new Pinecone.Builder("PINECONE_API_KEY") .withResponseMetadataListener(metadata -> { Timer.builder("pinecone.client.duration") .tag("operation", metadata.getOperationName()) .tag("index", metadata.getIndexName()) .tag("status", metadata.getStatus()) .register(meterRegistry) .record(metadata.getClientDurationMs(), TimeUnit.MILLISECONDS); }) .build(); ``` ## Visualizing metrics Once your metrics are flowing to a backend, you can build dashboards to monitor your Pinecone operations. If you're using Prometheus and Grafana, here are some useful queries: **P50 and P95 client latency:** ```promql theme={null} histogram_quantile(0.5, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le)) histogram_quantile(0.95, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le)) ``` **P95 latency by operation type:** ```promql theme={null} histogram_quantile(0.95, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le, db_operation_name)) ``` **Operation count by type:** ```promql theme={null} sum by (db_operation_name) (db_client_operation_count_total) ``` ## Understanding the latency breakdown The `ResponseMetadata` object provides three timing values that help you pinpoint the source of latency issues: | Component | Method | What it measures | | ---------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | Client duration | `getClientDurationMs()` | Total round-trip time from request start to response completion. Always available. | | Server duration | `getServerDurationMs()` | Time the Pinecone backend spent processing the request. Extracted from the `x-pinecone-response-duration-ms` response header. May be `null`. | | Network overhead | `getNetworkOverheadMs()` | The difference: client duration minus server duration. Includes network latency, serialization, and deserialization. May be `null`. | Use these values to diagnose performance issues: * **High server duration**: The bottleneck is on the Pinecone backend. Consider optimizing your query (e.g., reducing `topK`, using metadata filters), or check the [Pinecone status page](https://status.pinecone.io/). * **High network overhead**: The bottleneck is in the network path between your application and Pinecone. Consider deploying your application closer to your index's cloud region, or check for network issues. ## Limitations * **Data plane operations only.** Control plane operations (e.g., creating or deleting indexes) are not currently instrumented. * **Bulk import operations** are not yet instrumented. * **Server duration may be unavailable.** The `getServerDurationMs()` method returns `null` if the `x-pinecone-response-duration-ms` header is not present in the response. * **Synchronous callback.** The listener is called synchronously after the gRPC response is received. Keep implementations lightweight and non-blocking to avoid adding latency to your operations. For heavy processing, queue the metadata for async handling. * **Exceptions are swallowed.** Exceptions thrown by the listener are logged but do not affect the operation result. ## Best practices * **Keep listeners lightweight.** Record metrics or enqueue work -- don't do I/O or heavy computation in the callback. * **Follow OTel semantic conventions.** Use the attribute names shown in the [recommended metrics](#recommended-metrics) table for interoperability with standard dashboards and tooling. * **Monitor both client and server duration.** Tracking both lets you separate Pinecone backend performance from network conditions. * **Set alerts on error rates.** Use the `status` and `error.type` attributes to build alerts for elevated error rates across operations. # Pinecone Java SDK Source: https://docs.pinecone.io/reference/sdks/java/overview Install and use the Pinecone Java SDK to manage indexes and namespaces, upsert vectors, run semantic search, and call the Admin and Inference APIs from Java. For installation instructions and usage examples, see the [Pinecone Java SDK documentation](https://github.com/pinecone-io/pinecone-java-client). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-java-client/issues). ## Requirements The Pinecone Java SDK requires Java 1.8 or later. ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and Java SDK versions are as follows: | API version | SDK version | | :---------- | :---------- | | `2025-04` | v5.x | | `2025-01` | v4.x | | `2024-10` | v3.x | | `2024-07` | v2.x | | `2024-04` | v1.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. ## Install To install the latest version of the [Java SDK](https://github.com/pinecone-io/pinecone-java-client), add a dependency to the current module: ```shell Java theme={null} # Maven io.pinecone pinecone-client 5.0.0 # Gradle implementation "io.pinecone:pinecone-client:5.0.0" ``` Alternatively, you can download the standalone uberjar [pinecone-client-4.0.0-all.jar](https://repo1.maven.org/maven2/io/pinecone/pinecone-client/4.0.0/pinecone-client-4.0.0-all.jar), which bundles the Pinecone SDK and all dependencies together. You can include this in your classpath like you do with any third-party JAR without having to obtain the `pinecone-client` dependencies separately. ## Upgrade Before upgrading to `v4.0.0`, update all relevant code to account for the breaking changes explained [here](/release-notes/2025#2025-02-07-3). If you are already using the Java SDK, upgrade the dependency in the current module to the latest version: ```shell Java theme={null} # Maven io.pinecone pinecone-client 5.0.0 # Gradle implementation "io.pinecone:pinecone-client:5.0.0" ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance: ```Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class InitializeClientExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); } } ``` ## Observability The Java SDK supports capturing per-operation response metadata for all data plane operations, including client-side latency, server processing time, network overhead, and error details. You can use this metadata with [OpenTelemetry](https://opentelemetry.io/), Micrometer, or any other observability system to monitor your Pinecone usage in production. For setup instructions and examples, see [OpenTelemetry support](/reference/sdks/java/open-telemetry). # Reference Source: https://docs.pinecone.io/reference/sdks/java/reference Reference documentation for the Pinecone Java SDK, including client setup, types, and methods for managing indexes and vector data operations. # Pinecone Node.js SDK Source: https://docs.pinecone.io/reference/sdks/node/overview Install and use the Pinecone Node.js and TypeScript SDK to manage indexes, upsert vectors, run semantic search, and call the Admin and Inference APIs. For installation instructions, usage examples, and reference information, see the [Pinecone Node.js SDK documentation](https://sdk.pinecone.io/typescript/). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-ts-client/issues). ## Requirements The Pinecone Node SDK requires TypeScript 4.1 or later and Node 18.x or later. ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and Node.js SDK versions are as follows: | API version | SDK version | | :---------- | :---------- | | `2026-04` | v8.x | | `2025-10` | v7.x | | `2025-04` | v6.x | | `2025-01` | v5.x | | `2024-10` | v4.x | | `2024-07` | v3.x | | `2024-04` | v2.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. ## Install To install the latest version of the [Node.js SDK](https://github.com/pinecone-io/pinecone-ts-client), written in TypeScript, run the following command: ```Shell theme={null} npm install @pinecone-database/pinecone ``` To check your SDK version, run the following command: ```Shell theme={null} npm list | grep @pinecone-database/pinecone ``` ## Upgrade If you already have the Node.js SDK, upgrade to the latest version as follows: ```Shell theme={null} npm install @pinecone-database/pinecone@latest ``` ## Initialize Once installed, you can import the library and then use an [API key](/guides/projects/manage-api-keys) to initialize a client instance: ```JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); ``` To manage organizations, projects, API keys, and [role-based access control](/guides/production/manage-rbac), initialize an `AdminClient` with [service account](/guides/organizations/manage-service-accounts) credentials instead. This requires v8.2.0 or later: ```JavaScript theme={null} import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); ``` You can also pass `clientId` and `clientSecret` directly to the constructor instead of setting environment variables. ## Proxy configuration If your network setup requires you to interact with Pinecone through a proxy, you can pass a custom `ProxyAgent` from the [`undici` library](https://undici.nodejs.org/#/). Below is an example of how to construct an `undici` `ProxyAgent` that routes network traffic through a [`mitm` proxy server](https://mitmproxy.org/) while hitting Pinecone's `/indexes` endpoint. The following strategy relies on Node's native [`fetch`](https://nodejs.org/docs/latest/api/globals.html#fetch) implementation, released in Node v16 and stabilized in Node v21. If you are running Node versions 18-21, you may experience issues stemming from the instability of the feature. There are currently no known issues related to proxying in Node v18+. ```JavaScript JavaScript theme={null} import { Pinecone, type PineconeConfiguration, } from '@pinecone-database/pinecone'; import { Dispatcher, ProxyAgent } from 'undici'; import * as fs from 'fs'; const cert = fs.readFileSync('path/to/mitmproxy-ca-cert.pem'); const client = new ProxyAgent({ uri: 'https://your-proxy.com', requestTls: { port: 'YOUR_PROXY_SERVER_PORT', ca: cert, host: 'YOUR_PROXY_SERVER_HOST', }, }); const customFetch = ( input: string | URL | Request, init: RequestInit | undefined ) => { return fetch(input, { ...init, dispatcher: client as Dispatcher, keepalive: true, # optional }); }; const config: PineconeConfiguration = { apiKey: 'YOUR_API_KEY', fetchApi: customFetch, }; const pc = new Pinecone(config); const indexes = async () => { return await pc.listIndexes(); }; indexes().then((response) => { console.log('My indexes: ', response); }); ``` # Reference Source: https://docs.pinecone.io/reference/sdks/node/reference Reference documentation for the Pinecone Node.js SDK, including client setup, types, and methods for managing indexes and vector data operations. # Pinecone Python SDK Source: https://docs.pinecone.io/reference/sdks/python/overview Install and use the Pinecone SDK for Pinecone Python SDK: auth, typed clients, and API operations. For installation instructions, usage examples, and. For installation instructions, usage examples, and reference information, see the [Pinecone Python SDK documentation](https://sdk.pinecone.io/python/). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-python-client/issues). The Pinecone Python SDK is distributed on PyPI using the package name `pinecone`. By default, the `pinecone` package has a minimal set of dependencies and interacts with Pinecone via HTTP requests. However, you can install the following extras to unlock additional functionality: * `pinecone[grpc]` adds dependencies on `grpcio` and related libraries needed to run data operations such as upserts and queries over [gRPC](https://grpc.io/) for a modest performance improvement. * `pinecone[asyncio]` adds a dependency on `aiohttp` and enables usage of `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). For more details, see [Async requests](#async-requests). ## Requirements The Pinecone Python SDK requires Python 3.9 or later. It has been tested with CPython versions from 3.9 to 3.13. ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and Python SDK versions are as follows: | API version | SDK version | | :---------- | :------------ | | `2025-04` | v7.x | | `2025-01` | v6.x | | `2024-10` | v5.3.x | | `2024-07` | v5.0.x-v5.2.x | | `2024-04` | v4.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. ## Install To install the latest version of the [Python SDK](https://github.com/pinecone-io/pinecone-python-client), run the following command: ```shell theme={null} # Install the latest version pip install pinecone # Install the latest version with gRPC extras pip install "pinecone[grpc]" # Install the latest version with asyncio extras pip install "pinecone[asyncio]" ``` To install a specific version of the Python SDK, run the following command: ```shell pip theme={null} # Install a specific version pip install pinecone== # Install a specific version with gRPC extras pip install "pinecone[grpc]"== # Install a specific version with asyncio extras pip install "pinecone[asyncio]"== ``` To check your SDK version, run the following command: ```shell pip theme={null} pip show pinecone ``` To use the [Inference API](/reference/api/introduction#inference), you must be on version 5.0.0 or later. ### Install the Pinecone Assistant Python plugin As of Python SDK v7.0.0, the `pinecone-plugin-assistant` package is included by default. It is only necessary to install the package if you are using a version of the Python SDK prior to v7.0.0. ```shell HTTP theme={null} pip install --upgrade pinecone pinecone-plugin-assistant ``` ## Upgrade Before upgrading to `v6.0.0`, update all relevant code to account for the breaking changes explained [here](https://github.com/pinecone-io/pinecone-python-client/blob/main/docs/upgrading.md). Also, make sure to upgrade using the `pinecone` package name instead of `pinecone-client`; upgrading with the latter will not work as of `v6.0.0`. If you already have the Python SDK, upgrade to the latest version as follows: ```shell theme={null} # Upgrade to the latest version pip install pinecone --upgrade # Upgrade to the latest version with gRPC extras pip install "pinecone[grpc]" --upgrade # Upgrade to the latest version with asyncio extras pip install "pinecone[asyncio]" --upgrade ``` ## Initialize Once installed, you can import the library and then use an [API key](/guides/projects/manage-api-keys) to initialize a client instance: ```Python HTTP theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` ```python gRPC theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` When [creating an index](/guides/index-data/create-an-index), import the `ServerlessSpec` or `PodSpec` class as well: ```Python Serverless index theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ) ) ``` ```Python Pod-based index theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import PodSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=PodSpec( environment="us-west-1-gcp", pod_type="p1.x1", pods=1 ) ) ``` ## Proxy configuration If your network setup requires you to interact with Pinecone through a proxy, you will need to pass additional configuration using optional keyword parameters: * `proxy_url`: The location of your proxy. This could be an HTTP or HTTPS URL depending on your proxy setup. * `proxy_headers`: Accepts a python dictionary which can be used to pass any custom headers required by your proxy. If your proxy is protected by authentication, use this parameter to pass basic authentication headers with a digest of your username and password. The `make_headers` utility from `urllib3` can be used to help construct the dictionary. **Note:** Not supported with Asyncio. * `ssl_ca_certs`: By default, the client will perform SSL certificate verification using the CA bundle maintained by Mozilla in the [`certifi`](https://pypi.org/project/certifi/) package. If your proxy is using self-signed certicates, use this parameter to specify the path to the certificate (PEM format). * `ssl_verify`: SSL verification is enabled by default, but it is disabled when set to `False`. It is not recommened to go into production with SSL verification disabled. ```python HTTP theme={null} from pinecone import Pinecone import urllib3 from urllib3.util import make_headers pc = Pinecone( api_key="YOUR_API_KEY", proxy_url='https://your-proxy.com', proxy_headers=make_headers(proxy_basic_auth='username:password'), ssl_ca_certs='path/to/cert-bundle.pem' ) ``` ```python gRPC theme={null} from pinecone.grpc import PineconeGRPC as Pinecone import urllib3 from urllib3.util import make_headers pc = Pinecone( api_key="YOUR_API_KEY", proxy_url='https://your-proxy.com', proxy_headers=make_headers(proxy_basic_auth='username:password'), ssl_ca_certs='path/to/cert-bundle.pem' ) ``` ```python asyncio theme={null} import asyncio from pinecone import PineconeAsyncio async def main(): async with PineconeAsyncio( api_key="YOUR_API_KEY", proxy_url='https://your-proxy.com', ssl_ca_certs='path/to/cert-bundle.pem' ) as pc: # Do async things await pc.list_indexes() asyncio.run(main()) ``` ## Async requests Pinecone Python SDK versions 6.0.0 and later provide `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). Asyncio support makes it possible to use Pinecone with modern async web frameworks such as [FastAPI](https://fastapi.tiangolo.com/), [Quart](https://quart.palletsprojects.com/en/latest/), and [Sanic](https://sanic.dev/en/), and should significantly increase the efficiency of running requests in parallel. Use the [`PineconeAsyncio`](https://sdk.pinecone.io/python/asyncio.html) class to create and manage indexes and the [`IndexAsyncio`](https://sdk.pinecone.io/python/asyncio.html#pinecone.db_data.IndexAsyncio) class to read and write index data. To ensure that sessions are properly closed, use the `async with` syntax when creating `PineconeAsyncio` and `IndexAsyncio` objects. ```python Manage indexes theme={null} # pip install "pinecone[asyncio]" import asyncio from pinecone import PineconeAsyncio, ServerlessSpec async def main(): async with PineconeAsyncio(api_key="YOUR_API_KEY") as pc: if not await pc.has_index(index_name): desc = await pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ), deletion_protection="disabled", tags={ "environment": "development" } ) asyncio.run(main()) ``` ```python Read and write index data theme={null} # pip install "pinecone[asyncio]" import asyncio from pinecone import Pinecone async def main(): pc = Pinecone(api_key="YOUR_API_KEY") async with pc.IndexAsyncio(host="INDEX_HOST") as idx: await idx.upsert_records( namespace="example-namespace", records=[ { "id": "1", "title": "The Great Gatsby", "author": "F. Scott Fitzgerald", "description": "The story of the mysteriously wealthy Jay Gatsby and his love for the beautiful Daisy Buchanan.", "year": 1925, }, { "id": "2", "title": "To Kill a Mockingbird", "author": "Harper Lee", "description": "A young girl comes of age in the segregated American South and witnesses her father's courageous defense of an innocent black man.", "year": 1960, }, { "id": "3", "title": "1984", "author": "George Orwell", "description": "In a dystopian future, a totalitarian regime exercises absolute control through pervasive surveillance and propaganda.", "year": 1949, }, ] ) asyncio.run(main()) ``` ## Query across namespaces Each query is limited to a single [namespace](/guides/index-data/indexing-overview#namespaces). However, the Pinecone Python SDK provides a `query_namespaces` utility method to run a query in parallel across multiple namespaces in an index and then merge the result sets into a single ranked result set with the `top_k` most relevant results. The `query_namespaces` method accepts most of the same arguments as `query` with the addition of a required `namespaces` parameter. When using the Python SDK without gRPC extras, to get good performance, it is important to set values for the `pool_threads` and `connection_pool_maxsize` properties on the index client. The `pool_threads` setting is the number of threads available to execute requests, while `connection_pool_maxsize` is the number of cached http connections that will be held. Since these tasks are not computationally heavy and are mainly i/o bound, it should be okay to have a high ratio of threads to cpus. The combined results include the sum of all read unit usage used to perform the underlying queries for each namespace. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index( name="docs-example", pool_threads=50, # <-- make sure to set these connection_pool_maxsize=50, # <-- make sure to set these ) query_vec = [ 0.1, ...] # an embedding vector with same dimension as the index combined_results = index.query_namespaces( vector=query_vec, namespaces=['ns1', 'ns2', 'ns3', 'ns4'], metric="cosine", top_k=10, include_values=False, include_metadata=True, filter={"genre": { "$eq": "comedy" }}, show_progress=False, ) for scored_vec in combined_results.matches: print(scored_vec) print(combined_results.usage) ``` When using the Python SDK with gRPC extras, there is no need to set the `connection_pool_maxsize` because grpc makes efficient use of open connections by default. ```python Python theme={null} from pinecone.grpc import PineconeGRPC pc = PineconeGRPC(api_key="YOUR_API_KEY") index = pc.Index( name="docs-example", pool_threads=50, # <-- make sure to set this ) query_vec = [ 0.1, ...] # an embedding vector with same dimension as the index combined_results = index.query_namespaces( vector=query_vec, namespaces=['ns1', 'ns2', 'ns3', 'ns4'], metric="cosine", top_k=10, include_values=False, include_metadata=True, filter={"genre": { "$eq": "comedy" }}, show_progress=False, ) for scored_vec in combined_results.matches: print(scored_vec) print(combined_results.usage) ``` ## Upsert from a dataframe To quickly ingest data when using the [Python SDK](/reference/sdks/python/overview), use the `upsert_from_dataframe` method. The method includes retry logic and`batch_size`, and is performant especially with Parquet file data sets. The following example upserts the `uora_all-MiniLM-L6-bm25` dataset as a dataframe. ```Python Python theme={null} from pinecone import Pinecone, ServerlessSpec from pinecone_datasets import list_datasets, load_dataset pc = Pinecone(api_key="API_KEY") dataset = load_dataset("quora_all-MiniLM-L6-bm25") pc.create_index( name="docs-example", dimension=384, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ) ) # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.upsert_from_dataframe(dataset.drop(columns=["blob"])) ``` # Reference Source: https://docs.pinecone.io/reference/sdks/python/reference Reference documentation for the Pinecone Python SDK, including client setup, types, and methods for managing indexes and vector data operations. # Spark-Pinecone connector Source: https://docs.pinecone.io/reference/tools/pinecone-spark-connector Pinecone data tools: Use the connector to efficiently create, ingest, and update vector embeddings at scale with Databricks and Pinecone. Use the [`spark-pinecone` connector](https://github.com/pinecone-io/spark-pinecone/) to efficiently create, ingest, and update [vector embeddings](https://www.pinecone.io/learn/vector-embeddings/) at scale with [Databricks and Pinecone](/integrations/databricks). ## Install the Spark-Pinecone connector 1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster). 2. Configure the library as follows: 1. Select **File path/S3** as the **Library Source**. 2. Enter the S3 URI for the Pinecone assembly JAR file: ``` s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar ``` Databricks platform users must use the Pinecone assembly jar listed above to ensure that the proper dependecies are installed. 3. Click **Install**. 1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster). 2. Configure the library as follows: 1. Select **File path/S3** as the **Library Source**. 2. Enter the S3 URI for the Pinecone assembly JAR file: ``` s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar ``` 3. Click **Install**. 1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster). 2. Configure the library as follows: 1. [Download the Pinecone assembly JAR file](https://repo1.maven.org/maven2/io/pinecone/spark-pinecone_2.12/1.1.0/). 2. Select **Workspace** as the **Library Source**. 3. Upload the JAR file. 4. Click **Install**. ## Batch upsert To batch upsert embeddings to Pinecone: ```python Python theme={null} from pyspark import SparkConf from pyspark.sql import SparkSession from pyspark.sql.types import StructType, StructField, ArrayType, FloatType, StringType, LongType # Your API key and index name api_key = "PINECONE_API_KEY" index_name = "PINECONE_INDEX_NAME" source_tag = "PINECONE_SOURCE_TAG" COMMON_SCHEMA = StructType([ StructField("id", StringType(), False), StructField("namespace", StringType(), True), StructField("values", ArrayType(FloatType(), False), False), StructField("metadata", StringType(), True), StructField("sparse_values", StructType([ StructField("indices", ArrayType(LongType(), False), False), StructField("values", ArrayType(FloatType(), False), False) ]), True) ]) # Initialize Spark spark = SparkSession.builder.getOrCreate() # Read the file and apply the schema df = spark.read \ .option("multiLine", value = True) \ .option("mode", "PERMISSIVE") \ .schema(COMMON_SCHEMA) \ .json("src/test/resources/sample.jsonl") # Show if the read was successful df.show() # Write the dataFrame to Pinecone in batches df.write \ .option("pinecone.apiKey", api_key) \ .option("pinecone.indexName", index_name) \ .option("pinecone.sourceTag", source_tag) \ .format("io.pinecone.spark.pinecone.Pinecone") \ .mode("append") \ .save() ``` ```scala Scala theme={null} import io.pinecone.spark.pinecone.{COMMON_SCHEMA, PineconeOptions} import org.apache.spark.SparkConf import org.apache.spark.sql.{SaveMode, SparkSession} object MainApp extends App { // Your API key and index name val apiKey = "PINECONE_API_KEY" val indexName = "PINECONE_INDEX_NAME" val sourceTag = "PINECONE_SOURCE_TAG" // Configure Spark to run locally with all available cores val conf = new SparkConf() .setMaster("local[*]") // Create a Spark session with the defined configuration val spark = SparkSession.builder().config(conf).getOrCreate() // Read the JSON file into a DataFrame, applying the COMMON_SCHEMA val df = spark.read .option("multiLine", value = true) .option("mode", "PERMISSIVE") .schema(COMMON_SCHEMA) .json("src/test/resources/sample.jsonl") // path to sample.jsonl // Define Pinecone options as a Map val pineconeOptions = Map( PineconeOptions.PINECONE_API_KEY_CONF -> apiKey, PineconeOptions.PINECONE_INDEX_NAME_CONF -> indexName, PineconeOptions.PINECONE_SOURCE_TAG_CONF -> sourceTag ) // Show if the read was successful df.show(df.count().toInt) // Write the DataFrame to Pinecone using the defined options in batches df.write .options(pineconeOptions) .format("io.pinecone.spark.pinecone.Pinecone") .mode(SaveMode.Append) .save() } ``` For a guide on how to set up batch upserts, refer to the [Databricks integration page](/integrations/databricks#setup-guide). ## Stream upsert To stream upsert embeddings to Pinecone: ```python Python theme={null} from pyspark.sql import SparkSession from pyspark.sql.types import StructType, StructField, ArrayType, FloatType, StringType, LongType import os # Your API key and index name api_key = "PINECONE_API_KEY" index_name = "PINECONE_INDEX_NAME" source_tag = "PINECONE_SOURCE_TAG" COMMON_SCHEMA = StructType([ StructField("id", StringType(), False), StructField("namespace", StringType(), True), StructField("values", ArrayType(FloatType(), False), False), StructField("metadata", StringType(), True), StructField("sparse_values", StructType([ StructField("indices", ArrayType(LongType(), False), False), StructField("values", ArrayType(FloatType(), False), False) ]), True) ]) # Initialize Spark session spark = SparkSession.builder \ .appName("StreamUpsertExample") \ .config("spark.sql.shuffle.partitions", 3) \ .master("local") \ .getOrCreate() # Read the stream of JSON files, applying the schema from the input directory lines = spark.readStream \ .option("multiLine", True) \ .option("mode", "PERMISSIVE") \ .schema(COMMON_SCHEMA) \ .json("path/to/input/directory/") # Write the stream to Pinecone using the defined options upsert = lines.writeStream \ .format("io.pinecone.spark.pinecone.Pinecone") \ .option("pinecone.apiKey", api_key) \ .option("pinecone.indexName", index_name) \ .option("pinecone.sourceTag", source_tag) \ .option("checkpointLocation", "path/to/checkpoint/dir") \ .outputMode("append") \ .start() upsert.awaitTermination() ``` ```scala Scala theme={null} import io.pinecone.spark.pinecone.{COMMON_SCHEMA, PineconeOptions} import org.apache.spark.SparkConf import org.apache.spark.sql.{SaveMode, SparkSession} object MainApp extends App { // Your API key and index name val apiKey = "PINECONE_API_KEY" val indexName = "PINECONE_INDEX_NAME" // Create a Spark session val spark = SparkSession.builder() .appName("StreamUpsertExample") .config("spark.sql.shuffle.partitions", 3) .master("local") .getOrCreate() // Read the JSON files into a DataFrame, applying the COMMON_SCHEMA from input directory val lines = spark.readStream .option("multiLine", value = true) .option("mode", "PERMISSIVE") .schema(COMMON_SCHEMA) .json("path/to/input/directory/") // Define Pinecone options as a Map val pineconeOptions = Map( PineconeOptions.PINECONE_API_KEY_CONF -> System.getenv("PINECONE_API_KEY"), PineconeOptions.PINECONE_INDEX_NAME_CONF -> System.getenv("PINECONE_INDEX"), PineconeOptions.PINECONE_SOURCE_TAG_CONF -> System.getenv("PINECONE_SOURCE_TAG") ) // Write the stream to Pinecone using the defined options val upsert = lines .writeStream .format("io.pinecone.spark.pinecone.Pinecone") .options(pineconeOptions) .option("checkpointLocation", "path/to/checkpoint/dir") .outputMode("append") .start() upsert.awaitTermination() } ``` ## Learn more * [Spark-Pinecone connector setup guide](/integrations/databricks#setup-guide) * [GitHub](https://github.com/pinecone-io/spark-pinecone) # Authentication Source: https://docs.pinecone.io/reference/api/authentication Pinecone API authentication guide covering API key generation, SDK client setup, and HTTP header configuration for authorized requests. All requests to [Pinecone APIs](/reference/api/introduction) must contain a valid [API key](/guides/production/security-overview#api-keys) for the target project. ## Get an API key [Create a new API key](https://app.pinecone.io/organizations/-/projects/-/keys) in the Pinecone console, or use the connect widget below to generate a key.
Copy your generated key: ``` PINECONE_API_KEY="{{YOUR_API_KEY}}" # This API key has ReadWrite access to all indexes in your project. ``` ## Initialize a client When using a [Pinecone SDK](/reference/pinecone-sdks), initialize a client object with your API key and then reuse the authenicated client in subsquent function calls. For example: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key='YOUR_API_KEY') # Creates an index using the API key stored in the client 'pc'. pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud='aws', region='us-east-1' ) ) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); // Creates an index using the API key stored in the client 'pc'. await pc.createIndex({ name: 'docs-example', dimension: 1536, metric: 'cosine', spec: { serverless: { cloud: 'aws', region: 'us-east-1' } } }) ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.IndexModel; import org.openapitools.db_control.client.model.DeletionProtection; public class CreateServerlessIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); // Creates an index using the API key stored in the client 'pc'. pc.createServerlessIndex("docs-example", "cosine", 1536, "aws", "us-east-1"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v3/pinecone" ) 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) } indexName := "docs-example" vectorType := "dense" dimension := int32(1536) metric := pinecone.Cosine deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: indexName, VectorType: &vectorType, Dimension: &dimension, Metric: &metric, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: &deletionProtection, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", err) } else { fmt.Printf("Successfully created serverless index: %v", idx.Name) } } ``` ```shell curl theme={null} curl -s "https://api.pinecone.io/indexes" \ -H "Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud":"aws", "region": "us-east-1" } } }' ``` ## Add headers to an HTTP request All HTTP requests to Pinecone APIs must contain an `Api-Key` header that specifies a valid [API key](/guides/production/security-overview#api-keys) and must be encoded as JSON with the `Content-Type: application/json` header. For example: ```shell curl theme={null} curl https://api.pinecone.io/indexes \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud":"aws", "region": "us-east-1" } } }' ``` ## Troubleshooting Older versions of Pinecone required you to initialize a client with an `init` method that takes both `api_key` and `environment` parameters, for example: ```python Python theme={null} # Legacy initialization import pinecone pc = pinecone.init( api_key="PINECONE_API_KEY", environment="PINECONE_ENVIRONMENT" ) ``` ```javascript JavaScript theme={null} // Legacy initialization import { Pinecone } from '@pinecone-database/pinecone'; const pineconeClient = new PineconeClient(); await pineconeClient.init({ apiKey: 'PINECONE_API_KEY', environment: 'PINECONE_ENVIRONMENT', }); ``` In more recent versions of Pinecone, this has changed. Initialization no longer requires an `init` step, and cloud environment is defined for each index rather than an entire project. Client initialization now only requires an `api_key` parameter, for example: ```python Python theme={null} # New initialization from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` ```javascript JavaScript theme={null} // New initialization import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); ``` If you are receiving errors about initialization, upgrade your [Pinecone SDK](/reference/pinecone-sdks) to the latest version, for example: ```shell Python theme={null} # Upgrade Pinecone SDK pip install pinecone --upgrade ``` ```shell JavaScript theme={null} # Upgrade Pinecone SDK npm install @pinecone-database/pinecone@latest ``` Also, note that some third-party tutorials and examples still reference the older initialization method. In such cases, follow the example above and the examples throughout the Pinecone documentation instead. # Pinecone Database limits Source: https://docs.pinecone.io/reference/api/database-limits Reference for Pinecone Database limits, covering upsert, query, fetch, delete, import, namespace, and rate limits for serverless indexes. This page describes different types of limits for Pinecone Database. **Looking for a specific limit?** * To compare monthly included usage by plan, start with [read units](#read-units-per-month-per-org), [write units](#write-units-per-month-per-org), and [model usage limits](#monthly-usage-limits). * If you received a `429` error, check [rate limits](#rate-limits), especially request-per-second limits for query, upsert, update, delete, fetch, and list. * For projects, users, indexes, namespaces, storage, backups, and collections, see [object limits](#object-limits). * For batch sizes, metadata filters, and identifier lengths, see [operation limits](#operation-limits) and [identifier limits](#identifier-limits). ## Rate limits Rate limits help protect your applications from misuse and maintain the health of our shared serverless infrastructure. These limits are designed to support typical production workloads while ensuring reliable performance for all users. **Most rate limits can be adjusted upon request.** If you need higher limits to scale your application, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. Pinecone is committed to supporting your growth and can often accommodate higher throughput requirements. Rate limits vary based on [pricing plan](https://www.pinecone.io/pricing/) and apply to [serverless indexes](/guides/index-data/indexing-overview) only. Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Data plane operations: request-per-second limits Pinecone enforces rate limits on the number of API requests per second at the namespace level for data plane operations (query, upsert, delete, and update). These limits provide protection against excessive request rates. #### Affected operations The following operations are subject to request-per-second rate limiting: | Operation | Scope | Limit | | --------- | ------------- | ----- | | Query | Per namespace | 100 | | Upsert | Per namespace | 100 | | Delete | Per namespace | 100 | | Update | Per namespace | 100 | #### Error response When you exceed the request-per-second limit, you'll receive an HTTP `429 - TOO_MANY_REQUESTS` response. The error message indicates which operation exceeded the limit and includes the namespace name and limit value. See the individual limit sections below for specific error message formats. #### How request-per-second limits work with limits on read and write units Request-per-second limits are enforced in addition to existing read unit and write unit limits. Requests must not exceed any applicable limits: * Index-level limits - read and write unit limits, per index * Namespace-level limits - read and write unit limits, per namespace * Request-per-second limits - requests per second, per namespace If any limit is exceeded, the request fails with a 429 error. #### Recommendations If you're hitting request-per-second limits: 1. Implement retry logic. Use exponential backoff to handle rate limit errors gracefully. See [Error Handling Guide](/guides/production/error-handling#implement-retry-logic). 2. Pace your requests. Add client-side rate limiting to stay under limits. 3. Consider [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes), which don't have request-per-second limits and provide dedicated capacity for high-throughput workloads. 4. If you need higher limits, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. ### All rate limits #### Monthly usage limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :---------------------------------------------------------------------------- | :------------- | :------------- | :------------- | :-------------- | | [Read units per month per org](#read-units-per-month-per-org) | 1,000,000 | 2,000,000 | Unlimited | Unlimited | | [Write units per month per org](#write-units-per-month-per-org) | 2,000,000 | 5,000,000 | Unlimited | Unlimited | | [Embedding tokens per month per model](#embedding-tokens-per-month-per-model) | 5,000,000 | 10,000,000 | Unlimited | Unlimited | | [Rerank requests per month per model](#rerank-requests-per-month-per-model) | Model-specific | Model-specific | Model-specific | Model-specific | #### Data operation throughput limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :------------------------------------------------------------------------------------------------------------ | :----------- | :----------- | :------------ | :-------------- | | [Upsert size per second per namespace](#upsert-size-per-second-per-namespace) | 50 MB | 50 MB | 50 MB | 50 MB | | [Query read units per second per index](#query-read-units-per-second-per-index) | 2,000 | 2,000 | 2,000 | 2,000 | | [Query requests per second per namespace](#query-requests-per-second-per-namespace) | 100 | 100 | 100 | 100 | | [Update records per second per namespace](#update-records-per-second-per-namespace) | 100 | 100 | 100 | 100 | | [Update requests per second per namespace](#update-requests-per-second-per-namespace) | 100 | 100 | 100 | 100 | | [Update by metadata requests per second per namespace](#update-by-metadata-requests-per-second-per-namespace) | 5 | 5 | 5 | 5 | | [Update by metadata requests per second per index](#update-by-metadata-requests-per-second-per-index) | 500 | 500 | 500 | 500 | | [Upsert requests per second per namespace](#upsert-requests-per-second-per-namespace) | 100 | 100 | 100 | 100 | | [Fetch requests per second per index](#fetch-requests-per-second-per-index) | 100 | 100 | 100 | 100 | | [List requests per second per index](#list-requests-per-second-per-index) | 200 | 200 | 200 | 200 | | [Describe index stats requests per second per index](#describe-index-stats-requests-per-second-per-index) | 100 | 100 | 100 | 100 | | [Delete requests per second per namespace](#delete-requests-per-second-per-namespace) | 100 | 100 | 100 | 100 | | [Delete records per second per namespace](#delete-records-per-second-per-namespace) | 5,000 | 5,000 | 5,000 | 5,000 | | [Delete records per second per index](#delete-records-per-second-per-index) | 5,000 | 5,000 | 5,000 | 5,000 | | [Delete by metadata requests per second per namespace](#delete-by-metadata-requests-per-second-per-namespace) | 5 | 5 | 5 | 5 | | [Delete by metadata requests per second per index](#delete-by-metadata-requests-per-second-per-index) | 500 | 500 | 500 | 500 | #### Model throughput limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :------------------------------------------------------------------------------ | :------------- | :------------- | :------------- | :-------------- | | [Embedding tokens per minute per model](#embedding-tokens-per-minute-per-model) | Model-specific | Model-specific | Model-specific | Model-specific | | [Rerank requests per minute per model](#rerank-requests-per-minute-per-model) | Model-specific | Model-specific | Model-specific | Model-specific | ### Read units per month per org | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 1,000,000 | 2,000,000 | Unlimited | Unlimited | [Read units](/guides/manage-cost/understanding-cost#read-units) measure the compute, I/O, and network resources used by [fetch](/guides/manage-data/fetch-data), [query](/guides/search/search-overview), and [list](/guides/manage-data/list-record-ids) requests to serverless indexes. When you reach the monthly read unit limit for an organization, fetch, query, and list requests to serverless indexes in the organization will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached your read unit limit for the current month limit. To continue reading data, upgrade your plan. ``` To continue reading from serverless indexes in the organization, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). To check how close you are to the monthly read unit limit for your organization, do the following: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select the project. 3. Select any index in the project. 4. Look under **Usage**. Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Write units per month per org | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 2,000,000 | 5,000,000 | Unlimited | Unlimited | [Write units](/guides/manage-cost/understanding-cost#write-units) measure the storage and compute resources used by [upsert](/guides/index-data/upsert-data), [update](/guides/manage-data/update-data), and [delete](/guides/manage-data/delete-data) requests to serverless indexes. When you reach the monthly write unit limit for an organization, upsert, update, and delete requests to serverless indexes in the organization will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached your write unit limit for the current month. To continue writing data, upgrade your plan. ``` To continue writing data to serverless indexes in the organization, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). To check how close you are to the monthly write unit limit for your organization, do the following: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select the project. 3. Select any index in the project. 4. Look under **Usage**. ### Upsert size per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 50 MB | 50 MB | 50 MB | 50 MB | When you reach the per second [upsert](/guides/index-data/upsert-data) size for a namespace in an index, additional upserts will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max upsert size limit per second for index . Pace your upserts or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Query read units per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 2,000 | 2,000 | 2,000 | 2,000 | Pinecone measures [query](/guides/search/search-overview) usage in [read units](/guides/manage-cost/understanding-cost#read-units). When you reach the per second limit for queries across all namespaces in an index, additional queries will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max query read units per second for index . Pace your queries or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). To check how many read units a query consumes, [check the query response](/guides/manage-cost/monitor-usage-and-costs#read-units). Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Query requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [query](/guides/search/search-overview) limit for a namespace in an index, additional queries will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the query QPS limit for namespace {namespace_name} ({limit} QPS). Pace your queries, consider Dedicated Read Nodes for your index, or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Update records per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [update](/guides/manage-data/update-data) limit for a namespace in an index, additional updates will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max update records per second for namespace . Pace your update requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Update requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [update](/guides/manage-data/update-data) request limit for a namespace in an index, additional update requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the update QPS limit for namespace {namespace_name} ({limit} QPS). Pace your update requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). If you need to update most of the records in a large namespace, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) for help creating an export to enable a faster and more cost-effective approach. ### Update by metadata requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5 | 5 | 5 | 5 | When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit for a namespace in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max update by metadata requests per second for namespace . Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Update by metadata requests per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 500 | 500 | 500 | 500 | When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit across all namespaces in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max update by metadata requests per second for index . Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Upsert requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [upsert](/guides/index-data/upsert-data) request limit for a namespace in an index, additional upsert requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the upsert QPS limit for namespace {namespace_name} ({limit} QPS). Pace your upsert requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Fetch requests per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [fetch](/guides/manage-data/fetch-data) limit across all namespaces in an index, additional fetch requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max fetch requests per second for index . Pace your fetch requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### List requests per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 200 | 200 | 200 | 200 | When you reach the per second [list](/guides/manage-data/list-record-ids) limit across all namespaces in an index, additional list requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max list requests per second for index . Pace your list requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Describe index stats requests per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [describe index stats](/reference/api/2024-10/data-plane/describeindexstats) limit across all namespaces in an index, additional describe index stats requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max describe_index_stats requests per second for index . Pace your describe_index_stats requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [delete](/guides/manage-data/delete-data) request limit for a namespace in an index, additional delete requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the delete QPS limit for namespace {namespace_name} ({limit} QPS). Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete records per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5000 | 5000 | 5000 | 5000 | When you reach the per second [delete](/guides/manage-data/delete-data) limit for a namespace in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete records per second for namespace . Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete records per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5000 | 5000 | 5000 | 5000 | When you reach the per second [delete](/guides/manage-data/delete-data) limit across all namespaces in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete records per second for index . Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete by metadata requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5 | 5 | 5 | 5 | When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit for a namespace in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete by metadata requests per second for namespace . Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete by metadata requests per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 500 | 500 | 500 | 500 | When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit across all namespaces in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete by metadata requests per second for index . Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Embedding tokens per minute per model | Embedding model | Input type | Starter plan | Builder plan | Standard plan | Enterprise plan | | :--------------------------- | :--------- | :----------- | :----------- | :------------ | :-------------- | | `llama-text-embed-v2` | Passage | 250,000 | 250,000 | 1,000,000 | 1,000,000 | | | Query | 50,000 | 50,000 | 250,000 | 250,000 | | `multilingual-e5-large` | Passage | 250,000 | 250,000 | 1,000,000 | 1,000,000 | | | Query | 50,000 | 50,000 | 250,000 | 250,000 | | `pinecone-sparse-english-v0` | Passage | 250,000 | 250,000 | 3,000,000 | 3,000,000 | | | Query | 250,000 | 250,000 | 3,000,000 | 3,000,000 | When you reach the per minute token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max embedding tokens per minute () model ''' and input type '' for the current project. To increase this limit, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). Otherwise, you can handle this limit by [implementing retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). ### Embedding tokens per month per model | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5,000,000 | 10,000,000 | Unlimited | Unlimited | When you reach the monthly token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the embedding token limit () for model for the current month. To continue using this model, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Rerank requests per minute per model | Reranking model | Starter plan | Builder plan | Standard plan | Enterprise plan | | :--------------------- | :------------ | :------------ | :------------ | :-------------- | | `cohere-rerank-4-fast` | Not available | Not available | 300 | 300 | | `cohere-rerank-3.5` | Not available | Not available | 300 | 300 | | `bge-reranker-v2-m3` | 60 | 60 | 60 | 60 | | `pinecone-rerank-v0` | 60 | Not available | 60 | 60 | When you reach the per minute request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max rerank requests per minute () for model '' for the current project. To increase this limit, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Rerank requests per month per model | Reranking model | Starter plan | Builder plan | Standard plan | Enterprise plan | | :--------------------- | :------------ | :------------ | :------------ | :-------------- | | `cohere-rerank-4-fast` | Not available | Not available | Unlimited | Unlimited | | `cohere-rerank-3.5` | Not available | Not available | Unlimited | Unlimited | | `bge-reranker-v2-m3` | 500 | 1,000 | Unlimited | Unlimited | | `pinecone-rerank-v0` | 500 | Not available | Unlimited | Unlimited | When you reach the monthly request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the rerank request limit () for model for the current month. To continue using this model, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Inference requests per second or minute, per project | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :---------------------------- | :----------- | :----------- | :------------ | :-------------- | | Inference requests per second | 100 | 100 | 100 | 100 | | Inference requests per minute | 2000 | 2000 | 2000 | 2000 | When you reach the per second or per minute request limit, inference requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max inference requests per second () for the current project. ``` This error indicates per second or per minute, as applicable. To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). ## Object limits Object limits are restrictions on the number or size of objects in Pinecone. Object limits vary based on [pricing plan](https://www.pinecone.io/pricing/). | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :----------------------------------------------------------------------------- | :----------- | :----------- | :------------ | :-------------- | | [Projects per organization](#projects-per-organization) | 1 | 5 | 20 | 100 | | [Users per organization](#users-per-organization) | 2 | 5 | Unlimited | Unlimited | | [Serverless indexes per project](#serverless-indexes-per-project) 1 | 5 | 10 | 20 | 200 | | [Serverless index storage per org](#serverless-index-storage-per-org) | 2 GB | 10 GB | N/A | N/A | | [Namespaces per serverless index](#namespaces-per-serverless-index) | 100 | 1,000 | 100,000 | 100,000 | | [Serverless backups per project](#serverless-backups-per-project) | N/A | N/A | 500 | 1000 | | [Collections per project](#collections-per-project) | 100 | N/A | N/A | N/A | 1 On the Starter plan, all serverless indexes must be in the `us-east-1` region of AWS. Builder, Standard, and Enterprise plans can create indexes in any [supported region](/guides/index-data/create-an-index#cloud-regions).
### Projects per organization | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 1 | 5 | 20 | 100 | When you reach this quota for an organization, trying to [create projects](/guides/projects/create-a-project) will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max projects allowed in organization . To add more projects, upgrade your plan. ``` To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Users per organization | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 2 | 5 | Unlimited | Unlimited | When you reach this quota for an organization, trying to add users to the organization will fail. To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Serverless indexes per project | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5 | 10 | 20 | 200 | When you reach this quota for a project, trying to [create serverless indexes](/guides/index-data/create-an-index#create-a-serverless-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max serverless indexes allowed in project . Use namespaces to partition your data into logical groups, or upgrade your plan to add more serverless indexes. ``` To stay under this quota, consider using [namespaces](/guides/index-data/create-an-index#namespaces) instead of creating multiple indexes. Namespaces let you partition your data into logical groups within a single index. This approach not only helps you stay within index limits, but can also improve query performance and lower costs by limiting searches to relevant data subsets. To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Serverless index storage per org This limit applies to organizations on the Starter and Builder plans only. | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 2 GB | 10 GB | N/A | N/A | When you've reached this quota for an organization, updates and upserts into serverless indexes will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max storage allowed for organization . To update or upsert new data, delete records or upgrade your plan. ``` To continue writing data into your serverless indexes, [delete records](/guides/manage-data/delete-data) to bring your organization under the limit or [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Namespaces per serverless index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 1,000 | 100,000 | 100,000 | When you reach this quota for a serverless index, trying to [upsert records into a new namespace](/guides/index-data/upsert-data) in the index will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max namespaces allowed in serverless index . To add more namespaces, upgrade your plan. ``` To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). [Namespaces per serverless index](/reference/api/database-limits#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](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Serverless backups per project | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | N/A | N/A | 500 | 1000 | Backups are not available on the Starter or Builder plans. On the Standard and Enterprise plans, when you reach this quota for a project, trying to [create serverless backups](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Backup failed to create. Quota for number of backups per index exceeded. ``` ### Collections per project | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | N/A | N/A | N/A | When you reach this quota for a project, trying to [create collections](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max collections allowed in project . To add more collections, upgrade your plan. ``` To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ## Operation limits Operation limits are restrictions on the size, number, or other characteristics of operations in Pinecone. Operation limits are fixed and do not vary based on pricing plan. ### Upsert limits | Metric | Limit | | :----------------------------------------------------------------- | :------------------------------------------------------------ | | Max [batch size](/guides/index-data/upsert-data#upsert-in-batches) | 2 MB or 1000 records with vectors
96 records with text | | Max documents per upsert request | 1000 | | Max document upsert request size | 2 MB | | Max document size | 2 MB | | Max `full_text_search` string fields per schema | 100 | | Max size per `full_text_search` string field | 100 KB | | Max tokens per `full_text_search` string field | 10,000 | | Max bytes per token | 256 bytes | | Max filterable metadata size per document | 40 KB | | Max length for a record ID | 512 characters | | Max dimensionality for dense vectors | 20,000 | | Max non-zero values for sparse vectors | 2048 | | Max dimensionality for sparse vectors | 4.2 billion | The 40 KB filterable metadata limit does not apply to `full_text_search` text fields. ### Import limits If your import exceeds these limits, you'll get an error specifying the limit exceeded. See [Troubleshooting](/guides/index-data/import-data#troubleshooting) for details. | Metric | Limit | | :-------------------------------------------- | :-------- | | Max namespaces per import | 10,000 | | Max total input data size (on-demand indexes) | 1 TB | | Max total input data size (DRN indexes) | Unlimited | | Max files per import | 100,000 | | Max size per file | 10 GB | The total input data size limit does not apply to indexes with [dedicated read nodes](/guides/index-data/dedicated-read-nodes). Bulk import supports indexes without a schema definition (Parquet files) and indexes with document schemas ([JSONL files](/guides/search/full-text-search#bulk-import)). Semantic-text (auto-embedded) fields are not yet supported in document schemas. ### Query limits | Metric | Limit | | :---------------- | :----- | | Max `top_k` value | 10,000 | | Max result size | 4MB | The query result size is affected by the dimension of the dense vectors and whether or not dense vector values and metadata are included in the result. If a query fails due to exceeding the 4MB result size limit, choose a lower `top_k` value, or use `include_metadata=False` or `include_values=False` to exclude metadata or values from the result. For better performance, especially with higher `top_k` values, avoid including vector values unless you need them. ### Fetch limits **Fetch by ID limits:** | Metric | Limit | | :------------------------------- | :---- | | Max record IDs per fetch request | 1,000 | **Fetch by metadata limits:** | Metric | Limit | | :----------------------- | :---------------------------------- | | Max records per response | 10,000 | | Max response size | 4 MB | | Max request rate | 5 requests per second per namespace | To retrieve more than 10,000 matching records, paginate through results using the `paginationToken` parameter. See [Fetch records by metadata](/guides/manage-data/fetch-data#fetch-records-by-metadata). ### Delete limits | Metric | Limit | | :-------------------------------- | :---- | | Max record IDs per delete request | 1,000 | ### Metadata filter limits The following limits apply to [metadata filter expressions](/guides/search/filter-by-metadata#metadata-filter-expressions) used in query, delete, update, and fetch operations. | Limit | Value | Description | | :------------------------------------------ | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Maximum values per `$in` or `$nin` operator | 10,000 | Each `$in` or `$nin` operator accepts up to 10,000 values in its array. This limit applies per operator—if you have multiple `$in` operators in a single filter, each is independently limited to 10,000 values. | When you exceed this limit, the request will fail and return a `400 - BAD_REQUEST` error. #### Rationale Large `$in` operators can impact query performance and cost. Filters with thousands of values increase request payload size and end-to-end latency. Additionally, using large filters typically indicates a shared namespace architecture, which increases query costs—queries scan the entire namespace regardless of filters. #### Alternative approaches If you need to filter by more than 10,000 values, consider these alternatives: * **Use namespaces for tenant isolation**: Instead of filtering by tenant IDs within a single namespace, create separate namespaces for each tenant or tenant group. This can also reduce query costs. See [Design for multi-tenancy](/guides/index-data/data-modeling#design-for-multi-tenancy). * **Use broader access control groups**: Instead of filtering by individual user IDs, filter by organization, project, or role. This reduces the number of values in your `$in` filter. See [Design for multi-tenancy](/guides/index-data/data-modeling#use-access-control-groups-instead-of-individual-ids). * **Post-filter client-side**: Retrieve a larger top K without filtering (for example, top 1000), then filter results client-side. * **Run multiple queries**: Split your filter into multiple queries with smaller `$in` operators and combine the results client-side. To avoid hitting this limit in production, validate the size of your `$in` and `$nin` arrays in your application code before making the request to Pinecone. ## Identifier limits An identifier is a string of characters used to identify "named" [objects in Pinecone](/guides/get-started/concepts). The following Pinecone objects use strings as identifiers: | Object | Field | Max # characters | Allowed characters | | --------------------------------------------------------- | ----------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | [Organization](/guides/get-started/concepts#organization) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Project](/guides/get-started/concepts#project) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Index](/guides/get-started/concepts#index) | `name` | 45 |
  • `a-z`, `0-9`, and `-`
  • Must be lowercase
  • Cannot start or end with `-`
  • Cannot be empty
| | [Namespace](/guides/get-started/concepts#namespace) | `namespace` | 512 |
  • ASCII except `\0`
  • For the default namespace, use `""` (or `"__default__"`, in API versions `2025-04` and later)
| | [Record](/guides/get-started/concepts#record) | `id` | 512 |
  • ASCII except `\0`
  • Cannot be empty
| # Errors Source: https://docs.pinecone.io/reference/api/errors Pinecone REST API: Pinecone uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the range. Pinecone uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that failed given the information provided, and codes in the `5xx` range indicate an error with Pinecone's servers. For guidance on handling errors in production, see [Error handling](/guides/production/error-handling). ## 200 - OK The request succeeded. ## 201 - CREATED The request succeeded and a new resource was created. ## 202 - NO CONTENT The request succeeded, but there is no content to return. ## 400 - INVALID ARGUMENT The request failed due to an invalid argument. ## 401 - UNAUTHENTICATED The request failed due to a missing or invalid [API key](/guides/projects/understanding-projects#api-keys). ## 402 - PAYMENT REQUIRED The request failed due to delinquent payment or account deactivation for non-payment. See [Account deactivation for non-payment](/guides/organizations/manage-billing/non-payment-account-deactivation). ## 403 - FORBIDDEN The request failed due to an exceeded [quota](/reference/api/database-limits#object-limits) or [index deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection). ## 404 - NOT FOUND The request failed because the resource was not found. ## 409 - ALREADY EXISTS The request failed because the resource already exists. ## 412 - FAILED PRECONDITIONS The request failed due to preconditions not being met. | ## 422 - UNPROCESSABLE ENTITY The request failed because the server was unable to process the contained instructions. ## 429 - TOO MANY REQUESTS The request was [rate-limited](/reference/api/database-limits#rate-limits). [Implement retry logic with exponential backoff](/guides/production/error-handling#handle-rate-limits-429) to handle this error. ## 500 - UNKNOWN An internal server error occurred. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. ## 502 - BAD GATEWAY The API gateway received an invalid response from a backend service. This is typically a temporary error. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. ## 503 - UNAVAILABLE The server is currently unavailable. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. ## 504 - GATEWAY TIMEOUT The API gateway did not receive a timely response from the backend server. This can occur due to slow requests or backend processing delays. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. # API reference Source: https://docs.pinecone.io/reference/api/introduction Pinecone API reference overview for Database, Inference, and Admin endpoints with supported SDKs including Python, Node.js, Java, and Go. Pinecone's APIs let you interact programmatically with your Pinecone account. [SDK versions](/reference/pinecone-sdks#sdk-versions) are pinned to specific API versions. ## Database Use the Database API to store and query records in [Pinecone Database](/guides/get-started/quickstart). The following Pinecone SDKs support the Database API: ## Inference Use the Inference API to generate vector embeddings and rerank results using [embedding models](/guides/index-data/create-an-index#embedding-models) and [reranking models](/guides/search/rerank-results#reranking-models) hosted on Pinecone's infrastructure. There are two ways to use the Inference API: * As a standalone service, through the [Rerank documents](/reference/api/latest/inference/rerank) and [Generate vectors](/reference/api/latest/inference/generate-embeddings) endpoints. * As an integrated part of database operations, through the [Create an index with integrated embedding](/reference/api/latest/control-plane/create_for_model), [Upsert text](/reference/api/latest/data-plane/upsert_records), and [Search with text](/reference/api/latest/data-plane/search_records) endpoints. The following Pinecone SDKs support using the Inference API: # Known limitations Source: https://docs.pinecone.io/reference/api/known-limitations Known limitations and feature restrictions for Pinecone indexes, including upsert consistency, metadata rules, and serverless caveats. This page describes known limitations and feature restrictions in Pinecone. ## General * [Upserts](/guides/index-data/upsert-data) * Pinecone is eventually consistent, so there can be a slight delay before upserted records are available to query. After upserting records, use the [`describe_index_stats`](/reference/api/2024-10/data-plane/describeindexstats) operation to check if the current vector count matches the number of records you expect, although this method may not work for pod-based indexes with multiple replicas. * Only indexes using the [dotproduct distance metric](/guides/index-data/indexing-overview#dotproduct) support querying sparse-dense vectors. Upserting, updating, and fetching sparse-dense vectors in indexes with a different distance metric will succeed, but querying will return an error. * Indexes created before February 22, 2023 do not support sparse vectors. * [Metadata](/guides/index-data/upsert-data#upsert-with-metadata-filters) * Null metadata values aren't supported. Instead of setting a key to `null`, remove the key from the metadata payload. * Nested JSON objects are not supported. ## Serverless indexes Serverless indexes do not support the following features: * [Filtering index statistics by metadata](/reference/api/2024-10/data-plane/describeindexstats) * [Private endpoints](/guides/production/configure-private-endpoints) * This feature is available on AWS only. # API versioning Source: https://docs.pinecone.io/reference/api/versioning Pinecone REST API: Pinecone's APIs are versioned to ensure that your applications continue to work as expected as the platform evolves. Pinecone's APIs are versioned to ensure that your applications continue to work as expected as the platform evolves. Versions are named by release date in the format `YYYY-MM`, for example, `2025-10`. ## Release schedule On a quarterly basis, Pinecone releases a new **stable** API version as well as a **release candidate** of the next stable version. * **Stable:** Each stable version remains unchanged and supported for a minimum of 12 months. Since stable versions are released every 3 months, this means you have at least 9 months to test and migrate your app to the newest stable version before support for the previous version is removed. * **Release candidate:** The release candidate gives you insight into the upcoming changes in the next stable version. It is available for approximately 3 months before the release of the stable version and can include new features, improvements, and [breaking changes](#breaking-changes). Below is an example of Pinecone's release schedule: ## Specify an API version When using the API directly, it is important to specify an API version in your requests. If you don't, requests default to the oldest supported stable version. Once support for that version ends, your requests will default to the next oldest stable version, which could include breaking changes that require you to update your integration. To specify an API version, set the `X-Pinecone-Api-Version` header to the version name. For example, to use the latest stable version (`2026-04`) to describe an index, set the `X-Pinecone-Api-Version` header: ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/indexes/movie-recommendations" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" ``` To use an older version, specify that version instead. ## SDK versions Official [Pinecone SDKs](/reference/pinecone-sdks) provide convenient access to Pinecone APIs. SDK versions are pinned to specific API versions. When a new API version is released, a new version of the SDK is also released. For the mapping between SDK and API versions, see [SDK versions](/reference/pinecone-sdks#sdk-versions). ## Breaking changes Breaking changes are changes that can potentially break your integration with a Pinecone API. Breaking changes include: * Removing an entire operation * Removing or renaming a parameter * Removing or renaming a response field * Adding a new required parameter * Making a previously optional parameter required * Changing the type of a parameter or response field * Removing enum values * Adding a new validation rule to an existing parameter * Changing authentication or authorization requirements ## Non-breaking changes Non-breaking changes are additive and should not break your integration. Additive changes include: * Adding an operation * Adding an optional parameter * Adding an optional request header * Adding a response field * Adding a response header * Adding enum values ## Get updates To ensure you always know about upcoming API changes, follow the [Release notes](/release-notes/). # CLI authentication Source: https://docs.pinecone.io/reference/cli/authentication Authenticate the Pinecone CLI using user login, service accounts, or API keys, including auth priority and Admin API access rules. This document describes how to authenticate the Pinecone CLI to manage your Pinecone resources. ## Authentication methods | Method | Admin API | Control/data plane | Best for | | ----------------------------------- | --------- | ------------------ | -------------------------------- | | [User login](#user-login) | ✅ | ✅ | Interactive use | | [Service account](#service-account) | ✅ | ✅ | Automation with Admin API access | | [API key](#api-key) | ❌ | ✅ | Simple automation, CI/CD | ### User login Authenticate through a web browser. The token refreshes automatically and stays valid for up to 120 days (re-auth required after 30 days of inactivity). ```bash theme={null} pc auth login ``` The CLI auto-targets your default organization and its first project. Change with `pc target -o "my-org" -p "my-project"`. ### Service account Authenticate with credentials from a [service account](/guides/organizations/manage-service-accounts). ```bash theme={null} pc auth configure --client-id "ID" --client-secret "SECRET" # Or via environment variables export PINECONE_CLIENT_ID="your-client-id" export PINECONE_CLIENT_SECRET="your-client-secret" ``` The CLI auto-targets the service account's organization. For projects: auto-selects if one exists, prompts if multiple exist, or set manually with `pc target -p "my-project"`. ### API key Authenticate with an [API key](/guides/projects/manage-api-keys). API keys can't access the Admin API. ```bash theme={null} pc auth configure --api-key "YOUR_API_KEY" # Or via environment variable export PINECONE_API_KEY="your-api-key" ``` API keys are scoped to a specific project. When set, control/data plane operations use the **key's project**, ignoring any [target context](/reference/cli/target-context) you've set. ## Auth priority When multiple credentials exist, the CLI chooses based on operation type. Within each credential type, environment variables take precedence over stored configuration. **Control/data plane operations:** 1. API key 2. User login token (via [managed keys](#managed-keys)) 3. Service account (via [managed keys](#managed-keys)) **Admin API operations:** 1. User login token 2. Service account User login and service account are mutually exclusive when configured via CLI commands—each clears the other. However, service account env vars don't clear a stored user login token. **Example scenarios:** * If `PINECONE_API_KEY` is set, the CLI uses it for control/data plane operations, regardless of any stored API key. * If you're logged in via `pc auth login` and also have `PINECONE_CLIENT_ID`/`PINECONE_CLIENT_SECRET` set, the user login token is used for everything—the service account env vars are ignored. * If you have an API key configured and are also logged in, the API key is used for control/data plane operations, but user login is used for Admin API operations (since API keys can't access Admin API). ## Managed keys When using user login or service account (without a default API key), the CLI automatically creates and manages API keys for control/data plane operations. This happens transparently on first use. * **Stored locally:** `~/.config/pinecone/secrets.yaml` (permissions 0600) * **Stored remotely:** Visible in console as `pinecone-cli-{id}` with origin `cli_created` ```bash theme={null} # List locally tracked managed keys pc auth local-keys list # Delete managed keys (local + remote) pc auth local-keys prune # Delete only CLI-created managed keys pc auth local-keys prune --origin cli # Delete only user-created managed keys pc auth local-keys prune --origin user # Delete a specific API key by ID pc api-key delete --id "KEY_ID" ``` When you run `pc api-key create --store` for a project that already has a CLI-created managed key, the CLI automatically deletes the old remote key before storing the new one. ## Logging out ```bash theme={null} pc auth logout ``` Clears all local auth data: tokens, credentials, API keys, managed keys, and [target context](/reference/cli/target-context). `pc auth logout` doesn't delete managed keys from Pinecone's servers. Run `pc auth local-keys prune` first for full cleanup. ## Local storage Auth data is stored in `~/.config/pinecone/` with 0600 permissions: | File | Contents | | -------------- | ---------------------------------------------------------------- | | `secrets.yaml` | OAuth token, service account credentials, API keys, managed keys | | `state.yaml` | Target org/project | | `config.yaml` | CLI settings (color, environment) | ## Check status ```bash theme={null} pc auth status ``` Shows your current authentication method, target organization and project, token expiration (for user login), and environment configuration. # CLI command reference Source: https://docs.pinecone.io/reference/cli/command-reference Complete Pinecone CLI command reference covering syntax, subcommands, flags, help output, and exit codes for auth, index, and project. This document provides a complete reference for all Pinecone CLI commands. ## Command structure The Pinecone CLI uses a hierarchical command structure. Each command consists of a primary command followed by one or more subcommands and optional flags. ```bash theme={null} pc [flags] pc [flags] ``` For example: ```bash theme={null} # Top-level command with flags pc target -o "organization-name" -p "project-name" # Command (index) and subcommand (list) pc index list # Command (index) and subcommand (create) with flags pc index create \ --name my-index \ --dimension 1536 \ --metric cosine \ --cloud aws \ --region us-east-1 # Command (auth) and nested subcommands (local-keys prune) with flags pc auth local-keys prune --id proj-abc123 --skip-confirmation ``` ## Getting help The CLI provides help for commands at every level: ```bash theme={null} # top-level help pc --help pc -h # command help pc auth --help pc index --help pc project --help # subcommmand help pc index create --help pc project create --help pc auth configure --help # nested subcommand help pc auth local-keys prune --help ``` ## Exit codes All commands return exit code `0` for success and `1` for error. ## Available commands This section describes all commands offered by the Pinecone CLI. ### Top-level commands **Description** Authenticate via a web browser. After login, set a [target org and project](/reference/cli/target-context) with `pc target` before accessing data. This command defaults to an initial organization and project to which you have access (these values display in the terminal), but you can change them with `pc target`. **Usage** ```bash theme={null} pc login ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Log in via browser pc login # Then set target context pc target -o "my-org" -p "my-project" ``` This is an alias for `pc auth login`. Both commands perform the same operation. **Description** Clears all authentication data from local storage, including: * User login token * Service account credentials (client ID and secret) * Default (manually specified) API key * Locally managed keys (for all projects) * Target organization and project context **Usage** ```bash theme={null} pc logout ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Clear all credentials and context pc logout ``` This is an alias for `pc auth logout`. Both commands perform the same operation. Does not delete managed API keys from Pinecone's servers. Run `pc auth local-keys prune` before logging out to fully clean up. **Description** Set the target organization and project for the CLI. Supports interactive organization and project selection or direct specification via flags. For details, see [CLI target context](/reference/cli/target-context). **Usage** ```bash theme={null} pc target [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------ | :--------- | :----------------------------- | | `--clear` | | Clear target context | | `--json` | `-j` | Output in JSON format | | `--org` | `-o` | Organization name | | `--organization-id` | | Organization ID | | `--project` | `-p` | Project name | | `--project-id` | | Project ID | | `--show` | `-s` | Display current target context | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Interactive targeting after login pc login pc target # Set specific organization and project pc target -o "my-org" -p "my-project" # Show current context pc target --show # Clear all context pc target --clear ``` **Description** Displays version information for the CLI, including the version number, commit SHA, and build date. **Usage** ```bash theme={null} pc version ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Display version information pc version ``` **Description** Displays information about the currently authenticated user. To use this command, you must be authenticated via user login. **Usage** ```bash theme={null} pc whoami ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc whoami ``` This is an alias for `pc auth whoami`. Both commands perform the same operation. ### Authentication **Description** Selectively clears specific authentication data without affecting other credentials. At least one flag is required. **Usage** ```bash theme={null} pc auth clear [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------ | :--------- | :-------------------------------------------------- | | `--api-key` | | Clear only the default (manually specified) API key | | `--service-account` | | Clear only service account credentials | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Clear only the default (manually specified) API key pc auth clear --api-key pc auth status # Clear service account pc auth clear --service-account ``` More surgical than `pc auth logout`. Does not clear user login token or managed keys. For those, use `pc auth logout` or `pc auth local-keys prune`. **Description** Configures service account credentials or a default (manually specified) API key. Service accounts automatically target the organization and prompt for project selection, unless there is only one project. A default API key overrides any previously specified target organization/project context. When setting a service account, this operation clears the user login token, if one exists. For details, see [CLI target context](/reference/cli/target-context). **Usage** ```bash theme={null} pc auth configure [flags] ``` **Flags** | Long flag | Short flag | Description | | :---------------------- | :--------- | :--------------------------------------------------- | | `--api-key` | | Default API key to use for authentication | | `--client-id` | | Service account client ID | | `--client-secret` | | Service account client secret | | `--client-secret-stdin` | | Read client secret from stdin | | `--json` | `-j` | Output in JSON format | | `--project-id` | `-p` | Target project ID (optional, interactive if omitted) | | `--prompt-if-missing` | | Prompt for missing credentials | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Service account setup (auto-targets org and prompts for project) pc auth configure --client-id my-id --client-secret my-secret # Service account with specific project pc auth configure \ --client-id my-id \ --client-secret my-secret \ -p proj-123 # Default API key (overrides any target context) pc auth configure --api-key pcsk_abc123 ``` `pc auth configure --api-key "YOUR_API_KEY"` does the same thing as `pc config set-api-key "YOUR_API_KEY"`. To learn about targeting a project after authenticating with a service account, see [CLI target context](/reference/cli/target-context). **Description** Displays all [managed API keys](/reference/cli/authentication#managed-keys) stored locally by the CLI, with various details. **Usage** ```bash theme={null} pc auth local-keys list [flags] ``` **Flags** | Long flag | Short flag | Description | | :--------- | :--------- | :----------------------------------------- | | `--json` | `-j` | Output in JSON format | | `--reveal` | | Show the actual API key values (sensitive) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all locally managed keys pc auth local-keys list # Show key values pc auth local-keys list --reveal # After storing a key pc api-key create -n "my-key" --store pc auth local-keys list ``` **Description** Deletes locally stored [managed API keys](/reference/cli/authentication#managed-keys) from local storage and Pinecone's servers. Filters by origin (`cli`/`user`/`all`) or project ID. **Usage** ```bash theme={null} pc auth local-keys prune [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :---------------------------------------------------------- | | `--dry-run` | | Preview deletions without applying | | `--id` | | Prune keys for specific project ID only | | `--json` | `-j` | Output in JSON format | | `--origin` | `-o` | Filter by origin - `cli`, `user`, or `all` (default: `all`) | | `--skip-confirmation` | | Skip confirmation prompt | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Preview deletions pc auth local-keys prune --dry-run # Delete CLI-created keys only pc auth local-keys prune -o cli --skip-confirmation # Delete for specific project pc auth local-keys prune --id proj-abc123 # Before/after check pc auth local-keys list pc auth local-keys prune -o cli pc auth local-keys list ``` This deletes keys from both local storage and Pinecone servers. Use `--dry-run` to preview before committing. **Description** Authenticate via user login in the web browser. After login, [set a target org and project](/reference/cli/target-context). **Usage** ```bash theme={null} pc auth login pc login # shorthand ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Login and set target pc auth login pc target -o "my-org" -p "my-project" pc index list ``` Tokens refresh automatically and remain valid for up to 120 days. If you're inactive for more than 30 days, you must re-authenticate. Logging in clears any existing service account credentials. This command does the same thing as `pc login`. **Description** Clears all authentication data from local storage, including: * User login token * Service account credentials (client ID and secret) * Default (manually specified) API key * Locally managed keys (for all projects) * Target organization and project context **Usage** ```bash theme={null} pc auth logout ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Clear all credentials and context pc auth logout ``` This command does the same thing as `pc logout`. Does not delete managed API keys from Pinecone's servers. Run `pc auth local-keys prune` before logging out to fully clean up. **Description** Shows details about all configured authentication methods. **Usage** ```bash theme={null} pc auth status [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Check status after login pc auth login pc auth status # JSON output for scripting pc auth status --json ``` **Description** Displays information about the currently authenticated user. To use this command, you must be authenticated via user login. **Usage** ```bash theme={null} pc auth whoami ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc auth whoami ``` This command does the same thing as `pc whoami`. ### Indexes **Description** Modifies the configuration of an existing index. **Usage** ```bash theme={null} pc index configure [flags] ``` **Flags** | Long flag | Short flag | Description | | :----------------------- | :--------- | :-------------------------------------------------------------- | | `--index-name` | `-i` | Name of index to configure (required) | | `--deletion-protection` | | Enable or disable deletion protection - `enabled` or `disabled` | | `--tags` | | Custom user tags (key=value pairs) | | `--json` | `-j` | Output in JSON format | | **Dedicated read nodes** | | | | `--read-mode` | | Read capacity mode - `ondemand` or `dedicated` | | `--read-node-type` | | Node type for dedicated read - `b1` or `t1` | | `--read-shards` | | Number of shards for dedicated read capacity | | `--read-replicas` | | Number of replicas for dedicated read capacity | | **Integrated embedding** | | | | `--model` | | Embedding model name | | `--field-map` | | Field mapping for embedding (key=value pairs) | | `--read-parameters` | | Read parameters for embedding model (key=value pairs) | | `--write-parameters` | | Write parameters for embedding model (key=value pairs) | | **Pods** | | | | `--pod-type` | `-t` | Type of pod to use; can only upgrade when configuring | | `--replicas` | `-r` | Number of replicas of the index to configure | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Enable deletion protection pc index configure --index-name my-index --deletion-protection enabled # Add tags pc index configure --index-name my-index --tags environment=production,team=ml # Switch to dedicated read capacity pc index configure --index-name my-index \ --read-mode dedicated \ --read-node-type b1 \ --read-shards 2 \ --read-replicas 2 # Verify changes pc index describe --index-name my-index ``` Configuration changes may take some time to take effect. **Description** Creates a new index in your Pinecone project. Supports serverless, pod-based, integrated (with embedding model), and BYOC (Bring Your Own Cloud) index types. **Usage** ```bash theme={null} pc index create [flags] ``` **Flags** | Long flag | Short flag | Description | | :----------------------- | :--------- | :----------------------------------------------------------------------------- | | `--name` | `-n` | Index name (required) | | `--dimension` | `-d` | Vector dimension (required for standard indexes, optional for integrated) | | `--metric` | `-m` | Similarity metric - `cosine`, `euclidean`, or `dotproduct` (default: `cosine`) | | `--cloud` | `-c` | Cloud provider - `aws`, `gcp`, or `azure` | | `--region` | `-r` | Cloud region | | `--vector-type` | `-v` | Vector type - `dense` or `sparse` (serverless only) | | `--source-collection` | | Name of the source collection from which to create the index | | `--schema` | | Metadata schema to control which fields are indexed (comma-separated) | | `--deletion-protection` | | Deletion protection - `enabled` or `disabled` | | `--tags` | | Custom user tags (key=value pairs) | | `--json` | `-j` | Output in JSON format | | **Integrated indexes** | | | | `--model` | | Integrated embedding model name | | `--field-map` | | Field mapping for integrated embedding (key=value pairs) | | `--read-parameters` | | Read parameters for embedding model (key=value pairs) | | `--write-parameters` | | Write parameters for embedding model (key=value pairs) | | **BYOC indexes** | | | | `--byoc-environment` | | BYOC environment to use for the index | | **Dedicated read nodes** | | | | `--read-mode` | | Read capacity mode - `ondemand` or `dedicated` (default: `ondemand`) | | `--read-node-type` | | Node type for dedicated read - `b1` or `t1` | | `--read-shards` | | Number of shards (each shard provides 250 GB storage) | | `--read-replicas` | | Number of replicas for higher throughput | | **Pod-based indexes** | | | | `--environment` | | Environment of the index to create (for example, `us-east-1-aws`) | | `--pod-type` | | Type of pod to use (for example, `p1.x1`, `s1.x2`) | | `--shards` | | Number of shards (default: `1`) | | `--replicas` | | Number of replicas (default: `1`) | | `--metadata-config` | | Comma-separated list of metadata fields to index for search | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Create serverless index pc index create -n my-index -d 1536 -m cosine -c aws -r us-east-1 # Create sparse vector index pc index create -n sparse-index -m dotproduct -c aws -r us-east-1 --vector-type sparse # With integrated embedding model pc index create \ -n my-index \ -m cosine \ -c aws \ -r us-east-1 \ --model multilingual-e5-large \ --field-map text=chunk_text # With dedicated read capacity pc index create \ -n my-index \ -d 1536 \ -m cosine \ -c aws \ -r us-east-1 \ --read-mode dedicated \ --read-node-type b1 \ --read-shards 2 \ --read-replicas 2 # With deletion protection pc index create \ -n my-index \ -d 1536 \ -m cosine \ -c aws \ -r us-west-2 \ --deletion-protection enabled # From collection pc index create \ -n my-index \ -d 1536 \ -m cosine \ -c aws \ -r eu-west-1 \ --source-collection my-collection # Create pod-based index pc index create \ -n my-index \ -d 1536 \ -m cosine \ --environment us-east-1-aws \ --pod-type p1.x1 \ --shards 1 \ --replicas 1 ``` For a list of valid regions for a serverless index, see [Create a serverless index](/guides/index-data/create-an-index). **Description** Permanently deletes an index and all its data. This operation cannot be undone. **Usage** ```bash theme={null} pc index delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :--------------------------------------------------------- | | `--index-name` | `-i` | Name of index to delete (required) | | `--skip-confirmation` | | Skip the deletion confirmation prompt | | `--json` | `-j` | Output in JSON format (also skips the confirmation prompt) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete an index (prompts for confirmation) pc index delete --index-name my-index # Skip the confirmation prompt pc index delete --index-name my-index --skip-confirmation # List before and after pc index list pc index delete --index-name test-index --skip-confirmation pc index list ``` This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. **Description** Displays detailed configuration and status information for a specific index. **Usage** ```bash theme={null} pc index describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :-------------------- | | `--index-name` | `-i` | Index name (required) | | `--json` | `-j` | Output in JSON format | The `--name`/`-n` flag is a deprecated alias for `--index-name`/`-i`. **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe an index pc index describe -i my-index # JSON output pc index describe -i my-index -j # Check newly created index pc index create -n test-index -d 1536 -m cosine -c aws -r us-east-1 pc index describe -i test-index ``` **Description** Displays statistics for an index, including total vector count and namespace breakdown. Optionally filter results with a metadata filter. **Usage** ```bash theme={null} pc index stats [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--filter` | `-f` | Metadata filter (inline JSON, `./path.json`, or `-` for stdin) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Get stats for an index pc index stats -i my-index # Get stats with a metadata filter pc index stats -i my-index --filter '{"genre":{"$eq":"rock"}}' # Filter from file pc index stats -i my-index --filter ./filter.json # JSON output pc index stats -i my-index -j ``` **Description** Displays all indexes in your current target project, including various details. **Usage** ```bash theme={null} pc index list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------------------------------------- | | `--json` | `-j` | Output in JSON format (includes full index details) | | `--wide` | `-w` | Show additional columns (host, embed, tags) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all indexes pc index list # Show additional details pc index list --wide # JSON output for scripting pc index list -j # After creating indexes pc index create -n test-1 -d 768 -m cosine -c aws -r us-east-1 pc index list ``` ### Namespaces **Description** Creates a new namespace within an index. Namespaces allow you to partition vectors within an index. **Usage** ```bash theme={null} pc index namespace create [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :-------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--name` | | Namespace name (required) | | `--schema` | | Metadata schema for the namespace (comma-separated) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Create a namespace pc index namespace create -i my-index --name tenant-a # Create with metadata schema (comma-separated list of filterable metadata fields) pc index namespace create -i my-index --name tenant-b --schema "category,brand" # JSON output pc index namespace create -i my-index --name tenant-c -j ``` **Description** Deletes a namespace and all its vectors from an index. This operation cannot be undone. **Usage** ```bash theme={null} pc index namespace delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :--------------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--name` | | Namespace name (required); use `__default__` for the default namespace | | `--skip-confirmation` | | Skip the deletion confirmation prompt | | `--json` | `-j` | Output in JSON format (also skips the confirmation prompt) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete a namespace (prompts for confirmation) pc index namespace delete -i my-index --name tenant-a # Delete the default namespace pc index namespace delete -i my-index --name __default__ # Skip the confirmation prompt pc index namespace delete -i my-index --name tenant-a --skip-confirmation ``` Deleting a namespace removes all vectors in that namespace. This operation cannot be undone. **Description** Displays detailed information about a specific namespace, including record count and schema configuration. **Usage** ```bash theme={null} pc index namespace describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :--------------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--name` | | Namespace name (required); use `__default__` for the default namespace | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe a namespace pc index namespace describe -i my-index --name tenant-a # Describe the default namespace pc index namespace describe -i my-index --name __default__ # JSON output pc index namespace describe -i my-index --name tenant-a -j ``` **Description** Lists all namespaces within an index, including vector counts. **Usage** ```bash theme={null} pc index namespace list [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :----------------------------- | | `--index-name` | `-i` | Index name (required) | | `--limit` | `-l` | Maximum number of results | | `--pagination-token` | `-p` | Pagination token for next page | | `--prefix` | | Filter namespaces by prefix | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all namespaces pc index namespace list -i my-index # Filter by prefix pc index namespace list -i my-index --prefix "tenant-" # Limit results pc index namespace list -i my-index --limit 10 # JSON output pc index namespace list -i my-index -j ``` ### Vectors **Description** Deletes vectors from an index by ID, filter, or deletes all vectors in a namespace. **Usage** ```bash theme={null} pc index vector delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :------------------------------------------------------------------------ | | `--index-name` | `-i` | Index name (required) | | `--namespace` | | Namespace to delete from (default: `__default__`) | | `--ids` | | Vector IDs to delete (inline JSON array, `./path.json`, or `-` for stdin) | | `--filter` | | Metadata filter (inline JSON, `./path.json`, or `-` for stdin) | | `--all-vectors` | | Delete all vectors in the namespace | | `--skip-confirmation` | | Skip the confirmation prompt shown for `--all-vectors` | | `--json` | `-j` | Output in JSON format (also skips the confirmation prompt) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete specific vectors pc index vector delete -i my-index --ids '["id1"]' # Delete multiple vectors (inline JSON array, or JSON array in a file) pc index vector delete -i my-index --ids '["id1", "id2"]' # Delete by filter pc index vector delete -i my-index --filter '{"genre":"classical"}' # Delete all vectors in a namespace (prompts for confirmation) pc index vector delete -i my-index --namespace old-data --all-vectors # Delete all vectors without the prompt pc index vector delete -i my-index --namespace old-data --all-vectors --skip-confirmation ``` Only `--all-vectors` prompts for confirmation. Targeted deletes with `--ids` or `--filter` proceed without a prompt. Pass `--skip-confirmation` (or `--json`) to bypass the `--all-vectors` prompt. Vector deletion is permanent and cannot be undone. **Description** Retrieves vectors by their IDs or by a metadata filter, returning the vector values and metadata. **Usage** ```bash theme={null} pc index vector fetch [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :----------------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--namespace` | | Namespace to fetch from (default: `__default__`) | | `--ids` | | Vector IDs to fetch (inline JSON array, `./path.json`, or `-` for stdin) | | `--filter` | `-f` | Metadata filter (inline JSON, `./path.json`, or `-` for stdin) | | `--limit` | `-l` | Maximum number of vectors to fetch | | `--pagination-token` | `-p` | Pagination token for next page | | `--body` | | Request body JSON (inline, `./path.json`, or `-` for stdin) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Fetch specific vectors by ID pc index vector fetch -i my-index --ids '["123","456","789"]' # Fetch from a file pc index vector fetch -i my-index --ids ./ids.json # Fetch by metadata filter pc index vector fetch -i my-index --filter '{"genre":{"$eq":"rock"}}' # Fetch from a namespace pc index vector fetch -i my-index --namespace tenant-a --ids '["doc-123"]' # JSON output pc index vector fetch -i my-index --ids '["vec1"]' -j ``` Use either `--ids` or `--filter`, not both. When using `--ids`, pagination flags are not applicable. **Description** Lists vector IDs in a namespace with optional pagination. **Usage** ```bash theme={null} pc index vector list [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :---------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--namespace` | | Namespace to list from (default: `__default__`) | | `--limit` | `-l` | Maximum number of IDs to return | | `--pagination-token` | `-p` | Pagination token for next page | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List vector IDs pc index vector list -i my-index # List from a namespace with limit pc index vector list -i my-index --namespace tenant-a --limit 50 # JSON output pc index vector list -i my-index -j ``` **Description** Queries an index for similar vectors using dense vectors, sparse vectors, or vector ID. **Usage** ```bash theme={null} pc index vector query [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :-------------------------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--namespace` | | Namespace to query (default: `__default__`) | | `--id` | | Query by vector ID | | `--vector` | `-v` | Query vector values (inline JSON array, `./path.json`, or `-` for stdin) | | `--sparse-indices` | | Sparse vector indices (inline JSON uint32 array, `./path.json`, or `-` for stdin) | | `--sparse-values` | | Sparse vector values (inline JSON array, `./path.json`, or `-` for stdin) | | `--top-k` | `-k` | Number of results to return (default: 10) | | `--filter` | `-f` | Metadata filter (inline JSON, `./path.json`, or `-` for stdin) | | `--include-values` | | Include vector values in results | | `--include-metadata` | | Include metadata in results | | `--body` | | Request body JSON (inline, `./path.json`, or `-` for stdin) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Query by vector ID pc index vector query -i my-index --id "doc-123" -k 10 --include-metadata # Query by vector values pc index vector query -i my-index --vector '[0.1, 0.2, 0.3]' -k 25 # Query with metadata filter pc index vector query -i my-index \ --vector '[0.1, 0.2, 0.3]' \ --filter '{"genre":{"$eq":"sci-fi"}}' \ --include-metadata # Query from file (file contains a JSON array that specifies the query vector) pc index vector query -i my-index --vector ./embedding.json -k 20 # Query with sparse vectors (inline) pc index vector query -i my-index \ --sparse-indices '[0, 5, 12]' \ --sparse-values '[0.5, 0.3, 0.8]' \ -k 15 # Query with sparse vectors from files # indices.json: [0, 5, 12] # values.json: [0.5, 0.3, 0.8] pc index vector query -i my-index \ --sparse-indices ./indices.json \ --sparse-values ./values.json \ -k 15 # Query from stdin (extract embedding from a document) # doc.json: {"id": "doc-123", "embedding": [0.1, 0.2, 0.3], "text": "..."} jq -c '.embedding' doc.json | pc index vector query -i my-index --vector - -k 10 ``` Use `--id`, `--vector`, or sparse vectors (`--sparse-indices` and `--sparse-values`) to specify what to query against. These options are mutually exclusive. **Description** Updates a vector's values, sparse values, or metadata by ID, or updates metadata for multiple vectors matching a filter. **Usage** ```bash theme={null} pc index vector update [flags] ``` **Flags** | Long flag | Short flag | Description | | :----------------- | :--------- | :----------------------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--namespace` | | Namespace containing the vector (default: `__default__`) | | `--id` | | Vector ID to update | | `--values` | | New vector values (inline JSON array, `./path.json`, or `-` for stdin) | | `--sparse-indices` | | New sparse indices (inline JSON uint32 array, `./path.json`, or `-` for stdin) | | `--sparse-values` | | New sparse values (inline JSON array, `./path.json`, or `-` for stdin) | | `--metadata` | | New or updated metadata (inline JSON, `./path.json`, or `-` for stdin) | | `--filter` | | Metadata filter for bulk update (inline JSON, `./path.json`, or `-` for stdin) | | `--dry-run` | | Preview how many records would be updated without applying changes | | `--body` | | Request body JSON (inline, `./path.json`, or `-` for stdin) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Update metadata for a single vector pc index vector update -i my-index --id "vec1" --metadata '{"category":"updated"}' # Update values for a single vector pc index vector update -i my-index --id "vec1" --values '[0.2, 0.3, 0.4]' # Update sparse values # indices.json: [0, 5, 12] # values.json: [0.5, 0.3, 0.8] pc index vector update -i my-index --id "vec1" \ --sparse-indices ./indices.json \ --sparse-values ./values.json # Bulk update metadata by filter (preview first) pc index vector update -i my-index \ --filter '{"genre":{"$eq":"sci-fi"}}' \ --metadata '{"genre":"fantasy"}' \ --dry-run # Apply the bulk update pc index vector update -i my-index \ --filter '{"genre":{"$eq":"sci-fi"}}' \ --metadata '{"genre":"fantasy"}' ``` Use either `--id` for single vector updates or `--filter` for bulk updates. These options are mutually exclusive. **Description** Inserts or updates vectors in an index from a JSON or JSONL file, or inline JSON. The CLI automatically batches vectors for efficient uploading. Files can contain any number of vectors—the CLI splits them into batches and sends multiple API requests as needed. **Usage** ```bash theme={null} pc index vector upsert [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :--------------------------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--namespace` | | Namespace to upsert into (default: `__default__`) | | `--body` | | Request body JSON or JSONL (inline, `./path.json[l]`, or `-` for stdin) (required) | | `--batch-size` | `-b` | Size of batches to upsert (default: 500) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Upsert from JSON file (with "vectors" array) # vectors.json: {"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]} pc index vector upsert -i my-index --body ./vectors.json # Upsert with inline JSON pc index vector upsert -i my-index --body '{"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]}' # Upsert from JSONL file (one vector per line) # vectors.jsonl: {"id": "vec1", "values": [0.1, 0.2, 0.3]} # {"id": "vec2", "values": [0.4, 0.5, 0.6]} pc index vector upsert -i my-index --body ./vectors.jsonl # Upsert from stdin (same format as JSON or JSONL file) cat vectors.json | pc index vector upsert -i my-index --body - # Custom batch size (default: 500, max: 1000 per API request) pc index vector upsert -i my-index --body ./vectors.json --batch-size 1000 ``` **Batch size limits:** The API accepts up to 1000 vectors per request. The CLI defaults to batches of 500 vectors, but you can adjust this with `--batch-size` (up to 1000). Large files are automatically split into multiple batches. **File size:** There's no explicit file size limit—the CLI reads the entire file into memory and batches it automatically. Very large files are supported as long as they fit in available system memory. ### Records **Description** Search an index namespace with a query text, query vector, or record ID and return the most similar records, along with their similarity scores. Optionally, rerank the initial results based on their relevance to the query. Searching with text is supported only for indexes with an integrated embedding configured. Searching with a query vector or record ID is supported for all indexes. Exactly one primary query mode must be provided: * `--inputs` — query text (requires an index with integrated embedding) * `--id` — use an existing record's vector as the query * `--vector` — provide a dense vector directly (all index types) * `--sparse-indices` + `--sparse-values` — sparse vector (all index types) Combine `--vector` with `--sparse-indices`/`--sparse-values` for hybrid search. Use `--body` to pass a full request object; flags take precedence over `--body` when both specify the same field. **Usage** ```bash theme={null} pc index record search [flags] ``` **Flags** | Long flag | Short flag | Description | | :----------------- | :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--index-name` | `-i` | Name of the index to search (required) | | `--inputs` | | Query inputs for text search (inline JSON, `./path.json`, or `-` for stdin); requires integrated embedding. Mutually exclusive with `--id` and `--vector`. | | `--id` | | Use an existing record's vector by ID for the query. Mutually exclusive with `--inputs` and `--vector`. | | `--vector` | `-v` | Dense vector values to search against (inline JSON float32 array, `./path.json`, or `-` for stdin). Mutually exclusive with `--inputs` and `--id`. | | `--sparse-indices` | | Sparse vector indices (inline JSON int32 array, `./path.json`, or `-` for stdin). Must be used together with `--sparse-values`. | | `--sparse-values` | | Sparse vector values (inline JSON float32 array, `./path.json`, or `-` for stdin). Must be used together with `--sparse-indices`. | | `--top-k` | `-k` | Number of results to return (required) | | `--namespace` | | Namespace to search | | `--filter` | | Metadata filter (inline JSON, `./path.json`, or `-` for stdin) | | `--rerank` | | Re-score results using an inference model (inline JSON, `./path.json`, or `-` for stdin). Required fields: `model` (string), `rank_fields` (string array). | | `--match-terms` | | Keyword terms filter for sparse integrated indexes (inline JSON, `./path.json`, or `-` for stdin). Required field: `terms` (string array). Requires `--inputs`. | | `--fields` | | Fields to return in results (inline JSON string array, `./path.json`, or `-` for stdin) | | `--body` | | Full request body JSON (inline, `./path.json`, or `-` for stdin). Flags take precedence when both specify the same field. | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Examples** ```bash theme={null} # Text search (integrated embedding indexes only) pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --top-k 10 pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --namespace my-namespace --top-k 5 pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --filter '{"category":"health"}' --top-k 10 pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --fields '["_id","chunk_text","category"]' --top-k 10 pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --rerank '{"model":"bge-reranker-v2-m3","rank_fields":["chunk_text"]}' --top-k 10 pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --match-terms '{"terms":["vaccine","prevention"]}' --top-k 10 # Search by record ID for query vector (all index types) pc index record search --index-name my-index --id rec-123 --top-k 10 # Vector search (all index types) pc index record search --index-name my-index --vector '[0.1,0.2,0.3]' --top-k 10 pc index record search --index-name my-index --sparse-indices '[1,5,9]' --sparse-values '[0.4,0.8,0.2]' --top-k 10 pc index record search --index-name my-index --vector '[0.1,0.2,0.3]' --sparse-indices '[1,5,9]' --sparse-values '[0.4,0.8,0.2]' --top-k 10 # Full request body (must include top_k in the body) pc index record search --index-name my-index --body ./search.json ``` ```text CLI theme={null} Usage: 5 (read units) ID SCORE FIELDS rec-001 0.912340 {"category":"health","chunk_text":"vaccine research..."} rec-002 0.887210 {"category":"health","chunk_text":"disease prevention..."} ``` **Description** Upsert records into an integrated index namespace from a JSON or JSONL payload. The `--body` flag accepts a JSON object containing a `"records"` array of `IntegratedRecord` objects, a raw JSON array of records, or a JSONL stream of records (one object per line). The value can be inline JSON, a path to a `.json` or `.jsonl` file, or `-` to read from stdin. Records are sent in batches. The default batch size is 96 (the API maximum). Use `--batch-size` to send smaller batches. **Usage** ```bash theme={null} pc index record upsert [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :-------------------------------------------------------------------------------------- | | `--index-name` | `-i` | Name of the index to upsert into (required) | | `--body` | | Request body JSON or JSONL (inline JSON, `./path.json[l]`, or `-` for stdin) (required) | | `--namespace` | | Namespace to upsert into | | `--batch-size` | `-b` | Number of records per batch (default: `96`, max: `96`) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Examples** ```bash theme={null} # Upsert from a JSON file pc index record upsert --index-name my-index --body ./records.json # Upsert from a JSONL file into a specific namespace pc index record upsert --index-name my-index --namespace my-namespace --body ./records.jsonl # Upsert from stdin cat records.jsonl | pc index record upsert --index-name my-index --namespace my-namespace --body - ``` ### Collections **Description** Creates a static copy of a pod-based index as a collection. Collections can be used to store a snapshot of an index's data for backup or migration purposes. **Usage** ```bash theme={null} pc index collection create [flags] ``` **Flags** | Long flag | Short flag | Description | | :--------- | :--------- | :---------------------------------------------------------- | | `--name` | `-n` | Name to give the collection (required) | | `--source` | `-s` | Name of the pod-based index to use as the source (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Create a collection from a pod-based index pc index collection create --name my-collection --source my-index ``` ```text CLI theme={null} ATTRIBUTE VALUE Name my-collection State Initializing Dimension 1536 Size 0 VectorCount 0 Environment us-east-1-aws ``` **Description** Deletes a collection permanently. This action cannot be undone. **Usage** ```bash theme={null} pc index collection delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :--------------------------------------------------------- | | `--name` | `-n` | Name of the collection to delete (required) | | `--skip-confirmation` | | Skip the deletion confirmation prompt | | `--json` | `-j` | Output in JSON format (also skips the confirmation prompt) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete a collection (prompts for confirmation) pc index collection delete --name my-collection # Skip the confirmation prompt pc index collection delete --name my-collection --skip-confirmation ``` This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. **Description** Returns detailed information about a single collection, including its state, dimension, size, vector count, and environment. **Usage** ```bash theme={null} pc index collection describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------------------------------- | | `--name` | `-n` | Name of the collection to describe (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe a collection pc index collection describe --name my-collection ``` ```text CLI theme={null} ATTRIBUTE VALUE Name my-collection State Ready Dimension 1536 Size 104857600 VectorCount 10000 Environment us-east-1-aws ``` **Description** Lists all collections in your current project, sorted alphabetically by name. **Usage** ```bash theme={null} pc index collection list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all collections pc index collection list ``` ```text CLI theme={null} NAME DIMENSION SIZE STATUS VECTORS ENVIRONMENT my-collection 1536 104857600 Ready 10000 us-east-1-aws ``` ### Backups **Description** Creates a backup of a serverless index. Backups are static copies that only consume storage. **Usage** ```bash theme={null} pc index backup create [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------- | :--------- | :------------------------------------------------------------------- | | `--index-name` | `-i` | Name of the index to back up (required) | | `--name` | | Human-readable label for the backup (the backup ID is always a UUID) | | `--description` | `-d` | Description for the backup | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Create a backup pc index backup create -i my-index # Create with name and description pc index backup create -i my-index --name "nightly-backup" -d "Nightly backup before deployment" # JSON output pc index backup create -i my-index -j ``` **Description** Permanently deletes a backup. This operation cannot be undone. **Usage** ```bash theme={null} pc index backup delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :--------------------------------------------------------- | | `--id` | `-i` | Backup ID to delete (required) | | `--skip-confirmation` | | Skip the deletion confirmation prompt | | `--json` | `-j` | Output in JSON format (also skips the confirmation prompt) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete a backup by ID (prompts for confirmation) pc index backup delete -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f # Skip the confirmation prompt pc index backup delete -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f --skip-confirmation ``` This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. Backup deletion is permanent and cannot be undone. **Description** Displays detailed information about a specific backup. **Usage** ```bash theme={null} pc index backup describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :------------------------------- | | `--id` | `-i` | Backup ID to describe (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe a backup pc index backup describe -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f # JSON output pc index backup describe -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -j ``` **Description** Lists backups in the current project, optionally filtered by index name. **Usage** ```bash theme={null} pc index backup list [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :----------------------------- | | `--index-name` | `-i` | Filter backups by index name | | `--limit` | `-l` | Maximum number of results | | `--pagination-token` | `-p` | Pagination token for next page | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all backups in the project pc index backup list # List backups for a specific index pc index backup list --index-name my-index # Limit results pc index backup list --limit 10 # JSON output pc index backup list -j ``` **Description** Creates a new index from a backup. **Usage** ```bash theme={null} pc index restore [flags] ``` **Flags** | Long flag | Short flag | Description | | :---------------------- | :--------- | :--------------------------------------------------- | | `--id` | `-i` | Backup ID (UUID) to restore from (required) | | `--name` | `-n` | Name for the new index (required) | | `--deletion-protection` | | Enable deletion protection - `enabled` or `disabled` | | `--tags` | `-t` | Tags to apply to the new index (key=value pairs) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Restore an index from a backup pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index # Restore with tags and deletion protection pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index \ --tags env=prod,team=search \ --deletion-protection enabled # JSON output pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index -j ``` **Description** Displays the status and details of a restore job. **Usage** ```bash theme={null} pc index restore describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :------------------------------------ | | `--id` | `-i` | Restore job ID to describe (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe a restore job pc index restore describe -i rj-abc123 # JSON output pc index restore describe -i rj-abc123 -j ``` **Description** Lists all restore jobs in the current project. **Usage** ```bash theme={null} pc index restore list [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :----------------------------- | | `--limit` | `-l` | Maximum number of results | | `--pagination-token` | `-p` | Pagination token for next page | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List restore jobs pc index restore list # Limit results pc index restore list --limit 10 # JSON output pc index restore list -j ``` ### Imports **Description** Start an import that loads vector data from a storage provider into a serverless index. The URI must begin with the scheme of a supported provider (for example, `s3://`). For private buckets, configure a storage integration in the Pinecone console and pass the integration ID with `--integration-id`. Use `--error-mode` to control behavior when records fail: `continue` skips failing records and keeps going; `abort` stops the import on first error. Defaults to `continue`. **Usage** ```bash theme={null} pc index import start [flags] ``` **Flags** | Long flag | Short flag | Description | | :----------------- | :--------- | :-------------------------------------------------------------------- | | `--index-name` | `-i` | Name of the index to import into (required) | | `--uri` | `-u` | URI of the data to import, for example `s3://bucket/path/` (required) | | `--integration-id` | | Storage integration ID for private buckets | | `--error-mode` | | How to handle record errors: `continue` (default) or `abort` | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Examples** ```bash theme={null} # Start an import from a public S3 bucket pc index import start --index-name my-index --uri s3://my-bucket/data/ # Start an import from a private bucket using a storage integration pc index import start --index-name my-index --uri s3://my-bucket/data/ --integration-id intg-123 # Abort on the first error instead of continuing pc index import start --index-name my-index --uri s3://my-bucket/data/ --error-mode abort # JSON output pc index import start --index-name my-index --uri s3://my-bucket/data/ -j ``` ```text CLI theme={null} Import imp-abc123 started. ATTRIBUTE VALUE Import ID imp-abc123 ``` **Description** Show the current status and details of an import operation, including percent complete, records imported, and any error messages. **Usage** ```bash theme={null} pc index import describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :------------------------------------------------- | | `--index-name` | `-i` | Name of the index the import belongs to (required) | | `--id` | | ID of the import to describe (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe an import operation pc index import describe --index-name my-index --id import-123 # JSON output pc index import describe --index-name my-index --id import-123 -j ``` ```text CLI theme={null} ATTRIBUTE VALUE Import ID import-123 Status InProgress URI s3://my-bucket/data/ Percent Complete 45.0% Records Imported 450 Created At 2024-01-15 12:00:00 Finished At - Error None ``` **Description** List bulk import operations for the given index, with optional pagination. **Usage** ```bash theme={null} pc index import list [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :-------------------------------------------------------- | | `--index-name` | `-i` | Name of the index to list imports for (required) | | `--limit` | `-l` | Maximum number of imports to return | | `--pagination-token` | `-p` | Pagination token to continue a previous listing operation | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Examples** ```bash theme={null} # List all imports for an index pc index import list --index-name my-index # List imports with a page size limit pc index import list --index-name my-index --limit 10 # Continue paginating from a previous call pc index import list --index-name my-index --pagination-token eyJ... # JSON output pc index import list --index-name my-index -j ``` ```text CLI theme={null} IMPORT ID STATUS URI PERCENT RECORDS CREATED FINISHED imp-abc123 Completed s3://my-bucket/data/ 100.0% 1000 2024-01-15 12:00:00 2024-01-15 12:05:00 imp-def456 InProgress s3://other-bucket/data/ 45.0% 450 2024-01-15 13:00:00 - ``` **Description** Cancel an import operation that is currently pending or in progress. Already-completed or failed imports cannot be canceled. **Usage** ```bash theme={null} pc index import cancel [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :------------------------------------------------- | | `--index-name` | `-i` | Name of the index the import belongs to (required) | | `--id` | | ID of the import to cancel (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Cancel an import operation pc index import cancel --index-name my-index --id import-123 # JSON output pc index import cancel --index-name my-index --id import-123 -j ``` ```text CLI theme={null} Import import-123 canceled. ``` ### Projects **Description** Creates a new project in your [target organization](/reference/cli/target-context), using the specified configuration. **Usage** ```bash theme={null} pc project create [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :------------------------------------------------------------- | | `--force-encryption` | | Enable encryption with CMEK | | `--json` | `-j` | Output in JSON format | | `--name` | `-n` | Project name (required) | | `--target` | | Automatically target the project in the CLI after it's created | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Basic project creation pc project create -n "demo-project" ``` **Description** Permanently deletes a project and all its resources. This operation cannot be undone. **Usage** ```bash theme={null} pc project delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :---------------------------------------------------------- | | `--id` | `-i` | Project ID (optional, uses target project if not specified) | | `--json` | `-j` | Output in JSON format | | `--skip-confirmation` | | Skip confirmation prompt | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete target project pc project delete # Delete specific project pc project delete -i proj-abc123 # Skip confirmation pc project delete -i proj-abc123 --skip-confirmation ``` Must delete all indexes and collections in the project first. If the deleted project is your current target, set a new target after deleting it. **Description** Displays detailed information about a specific project, including various details. **Usage** ```bash theme={null} pc project describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--id` | `-i` | Project ID (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe a project pc project describe -i proj-abc123 # JSON output pc project describe -i proj-abc123 --json # Find ID and describe pc project list pc project describe -i proj-abc123 ``` **Description** Displays all projects in your [target organization](/reference/cli/target-context), including various details. **Usage** ```bash theme={null} pc project list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all projects pc project list # JSON output pc project list --json # List after login pc auth login pc auth target -o "my-org" pc project list ``` **Description** Modifies the configuration of the [target project](/reference/cli/target-context), or a specific project ID. **Usage** ```bash theme={null} pc project update [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :---------------------------------- | | `--force-encryption` | `-f` | Enable/disable encryption with CMEK | | `--id` | `-i` | Project ID (required) | | `--json` | `-j` | Output in JSON format | | `--name` | `-n` | New project name | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Update name pc project update -i proj-abc123 -n "new-name" ``` ### Organizations **Description** Permanently deletes an organization and all its resources. This operation cannot be undone. **Usage** ```bash theme={null} pc organization delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :------------------------- | | `--id` | `-i` | Organization ID (required) | | `--json` | `-j` | Output in JSON format | | `--skip-confirmation` | | Skip confirmation prompt | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete an organization pc organization delete -i org-abc123 # Skip confirmation pc organization delete -i org-abc123 --skip-confirmation ``` This is a highly destructive action. Deletion is permanent. If the deleted organization is your current [target](/reference/cli/target-context), set a new target after deleting. **Description** Displays detailed information about a specific organization, including name, ID, creation date, payment status, plan, and support tier. **Usage** ```bash theme={null} pc organization describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :------------------------- | | `--id` | `-i` | Organization ID (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe an organization pc organization describe -i org-abc123 # JSON output pc organization describe -i org-abc123 --json # Find ID and describe pc organization list pc organization describe -i org-abc123 ``` **Description** Displays all organizations that the authenticated user has access to, including name, ID, creation date, payment status, plan, and support tier. **Usage** ```bash theme={null} pc organization list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all organizations pc organization list # JSON output pc organization list --json # List after login pc auth login pc organization list ``` **Description** Modifies the configuration of the [target organization](/reference/cli/target-context), or a specific organization ID. **Usage** ```bash theme={null} pc organization update [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :------------------------- | | `--id` | `-i` | Organization ID (required) | | `--json` | `-j` | Output in JSON format | | `--name` | `-n` | New organization name | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Update name pc organization update -i org-abc123 -n "new-name" # Verify changes pc organization update -i org-abc123 -n "Acme Corp" pc organization describe -i org-abc123 ``` ### API keys **Description** Creates a new API key for the current [target project](/reference/cli/target-context) or a specific project ID. Optionally stores the key locally for CLI use. **Usage** ```bash theme={null} pc api-key create [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------------------------------------------------------------------------- | | `--id` | `-i` | Project ID (optional, uses target project if not specified) | | `--json` | `-j` | Output in JSON format | | `--name` | `-n` | Key name (required) | | `--roles` | | Roles to assign (default: `ProjectEditor`) | | `--store` | | Store the key locally for CLI use (automatically replaces any existing CLI-managed key) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Basic key creation pc api-key create -n "my-key" # Create and store locally pc api-key create -n "my-key" --store # Create with specific role pc api-key create -n "my-key" --store --roles ProjectEditor # Create for specific project pc api-key create -n "my-key" -i proj-abc123 ``` API keys are scoped to a specific organization and project. **Description** Permanently deletes an API key. Applications using this key immediately lose access. **Usage** ```bash theme={null} pc api-key delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :----------------------- | | `--id` | `-i` | API key ID (required) | | `--skip-confirmation` | | Skip confirmation prompt | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete an API key pc api-key delete -i key-abc123 # Skip confirmation pc api-key delete -i key-abc123 --skip-confirmation # Delete and clean up local storage pc api-key delete -i key-abc123 pc auth local-keys prune --skip-confirmation ``` Deletion is permanent. Applications using this key immediately lose access to Pinecone. **Description** Displays detailed information about a specific API key, including its name, ID, project ID, and roles. **Usage** ```bash theme={null} pc api-key describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--id` | `-i` | API key ID (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe an API key pc api-key describe -i key-abc123 # JSON output pc api-key describe -i key-abc123 --json # Find ID and describe pc api-key list pc api-key describe -i key-abc123 ``` Does not display the actual key value. **Description** Displays a list of all of the [target project's](/reference/cli/target-context) API keys, as found in Pinecone (regardless of whether they are stored locally by the CLI). Displays various details about each key, including name, ID, project ID, and roles. **Usage** ```bash theme={null} pc api-key list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :---------------------------------------------------------- | | `--id` | `-i` | Project ID (optional, uses target project if not specified) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List keys for target project pc api-key list # List for specific project pc api-key list -i proj-abc123 # JSON output pc api-key list --json ``` Does not display key values. **Description** Updates the name and roles of an API key. **Usage** ```bash theme={null} pc api-key update [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--id` | `-i` | API key ID (required) | | `--json` | `-j` | Output in JSON format | | `--name` | `-n` | New key name | | `--roles` | `-r` | Roles to assign | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Update name pc api-key update -i key-abc123 -n "new-name" # Update roles pc api-key update -i key-abc123 -r ProjectEditor # Verify changes pc api-key update -i key-abc123 -n "production-key" pc api-key describe -i key-abc123 ``` Cannot change the actual key. If you need a different key, create a new one. ### Config **Description** Lists all CLI configuration settings and their current values. Sensitive values like `api-key` are masked by default; use `--reveal` to see the full value. Hidden settings such as `environment` are included when `--all` is passed. **Usage** ```bash theme={null} pc config list [flags] ``` **Flags** | Long flag | Short flag | Description | | :--------- | :--------- | :-------------------------------------------------------- | | `--reveal` | | Reveal the full value for sensitive settings like api-key | | `--json` | `-j` | Output in JSON format | | `--all` | | Include hidden settings such as environment | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc config list pc config list --all pc config list --reveal pc config list --json ``` ```text CLI theme={null} KEY VALUE ENV VAR NAME ENV VAR OVERRIDE DESCRIPTION api-key ****abcd**** PINECONE_API_KEY false Default API key for authenticating with Pinecone color true Enable colored output ``` **Description** Gets the current value of a configuration setting. Valid keys are: `api-key`, `color`, `environment`. Sensitive values like `api-key` are masked by default; use `--reveal` to see the full value. **Usage** ```bash theme={null} pc config get [flags] ``` **Flags** | Long flag | Short flag | Description | | :--------- | :--------- | :-------------------------------------------------------- | | `--reveal` | | Reveal the full value for sensitive settings like api-key | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc config get api-key pc config get api-key --reveal pc config get environment pc config get color ``` **Description** Displays detailed information about a specific CLI configuration setting, including its current value, whether an environment variable is overriding it, and valid values. Valid keys are: `api-key`, `color`, `environment`. **Usage** ```bash theme={null} pc config describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :--------- | :--------- | :-------------------------------------------------------- | | `--reveal` | | Reveal the full value for sensitive settings like api-key | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc config describe api-key pc config describe color pc config describe color --json ``` ```text CLI theme={null} KEY api-key VALUE ****abcd**** ENV VAR NAME $PINECONE_API_KEY ENV VAR OVERRIDE false SENSITIVE true DESCRIPTION Default API key for authenticating with Pinecone ``` **Description** Sets a CLI configuration value. Valid keys are: `api-key`, `color`, `environment`. The value is persisted to the local config file. **Usage** ```bash theme={null} pc config set [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc config set api-key pcsk_... pc config set environment staging pc config set color false ``` **Description** Resets a CLI configuration value to its default. Valid keys are: `api-key`, `color`, `environment`. **Usage** ```bash theme={null} pc config unset [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc config unset api-key pc config unset color ``` # CLI quickstart Source: https://docs.pinecone.io/reference/cli/quickstart Pinecone CLI quickstart for installing pc, authenticating, and managing indexes, vectors, and data imports directly from your terminal. The Pinecone CLI (`pc`) lets you manage Pinecone resources directly from your terminal. ## Install ```bash theme={null} brew tap pinecone-io/tap brew install pinecone-io/tap/pinecone ``` Pre-built binaries for macOS, Linux, and Windows are available on the [GitHub Releases page](https://github.com/pinecone-io/cli/releases). | Platform | Architectures | | :------- | :------------------------------------- | | macOS | Intel (x86\_64), Apple Silicon (ARM64) | | Linux | x86\_64, ARM64, i386 | | Windows | x86\_64, i386 | ## Authenticate ```bash theme={null} pc auth login ``` Visit the URL in your terminal to sign in. The CLI automatically sets your default organization and project. To target a different org/project: ```bash theme={null} pc target -o "my-org" -p "my-project" ``` For CI/CD or automation, you can also authenticate with a [service account](/reference/cli/authentication#service-account) or [API key](/reference/cli/authentication#api-key). ## Manage indexes ```bash theme={null} # List indexes pc index list # Create an index pc index create -n my-index -d 3 -m cosine -c aws -r us-east-1 # Get index details pc index describe -i my-index # Get index statistics pc index stats -i my-index ``` ## Work with vectors ```bash theme={null} # Upsert vectors (from file or inline JSON) pc index vector upsert -i my-index \ --body '{"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]}' # Import from a large dataset in object storage (S3, GCS, Azure) pc index import start -i my-index --uri s3://my-bucket/data/ # Check the progress of an import operation pc index import list --i my-index pc index import describe --i my-index --id import-123 # Query (vector can be inline or in a file) pc index vector query -i my-index \ --vector '[0.1, 0.2, 0.3]' \ --top-k 10 \ --include-metadata # Fetch by ID (from file or inline JSON) pc index vector fetch -i my-index --ids '["vec1","vec2"]' # List vector IDs from an index pc index vector list -i my-index ``` ## Manage namespaces ```bash theme={null} # List namespaces pc index namespace list -i my-index # Create a namespace pc index namespace create -i my-index --name tenant-a # Delete a namespace pc index namespace delete -i my-index --name tenant-a ``` ## Back up and restore ```bash theme={null} # Create a backup pc index backup create -i my-index --name "my-index-backup" # List backups (show index, backup name, backup ID, etc.) pc index backup list -i my-index # Restore from backup (by ID, not name) pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index ``` ## JSON output Add `-j` to any command for JSON output: ```bash theme={null} pc index list -j pc index describe -i my-index -j ``` ## Getting help Use `-h` or `--help` with any command to see available options: ```bash theme={null} pc -h pc index -h pc index create -h ``` ## Next steps * [Command reference](/reference/cli/command-reference) — Full list of commands and flags * [Authentication](/reference/cli/authentication) — Service accounts, API keys, and auth priority * [Target context](/reference/cli/target-context) — How org/project targeting works # CLI target context Source: https://docs.pinecone.io/reference/cli/target-context Pinecone CLI: The CLI's **target context** determines which organization and project your commands operate on. You must authenticate before setting target. The CLI's **target context** determines which organization and project your commands operate on. You must [authenticate](/reference/cli/authentication) before setting target context. ## Flags | Flag | Short | Default | Description | | ------------------- | ----- | ------- | --------------------------------------------------------------------------------- | | `--org` | `-o` | — | Target organization by name. Mutually exclusive with `--organization-id`. | | `--organization-id` | — | — | Target organization by ID. Mutually exclusive with `--org`. | | `--project` | `-p` | — | Target project by name. Mutually exclusive with `--project-id`. | | `--project-id` | — | — | Target project by ID. Mutually exclusive with `--project`. | | `--show` | `-s` | `false` | Show the current target context. | | `--clear` | — | `false` | Clear the stored target context. | | `--json` | `-j` | `false` | Output as JSON. In non-TTY environments (CI/CD, pipes), JSON output is automatic. | `--org` and `--organization-id` are mutually exclusive — use one or the other. The same applies to `--project` and `--project-id`. ## How operations use target context | Operation type | Scope | | -------------------------------- | ---------------------------------------- | | Control plane (indexes, backups) | Target project | | Data plane (vectors, namespaces) | Target project + specified index | | Admin API (organizations) | No target context needed | | Admin API (projects) | Target organization | | Admin API (API keys) | Target project (unless `--id` specified) | ## Target context by auth method ### User login After `pc auth login`, the CLI auto-targets your default organization and its first project. ```bash theme={null} # Change target pc target -o "my-org" -p "my-project" ``` ### Service account **Via CLI command:** After `pc auth configure --client-id --client-secret`, the CLI auto-targets the service account's organization. For the project: * If one project exists, it's auto-targeted * If multiple exist, you're prompted (or use `--project-id`) * If none exist, create one and target it manually **Via environment variables:** If using `PINECONE_CLIENT_ID` and `PINECONE_CLIENT_SECRET` without running `pc auth configure`, no target context is set automatically. Run `pc target` to set it. ```bash theme={null} # Change project (org is fixed to the service account's org) pc target -p "my-project" # Or select interactively pc target ``` ### API key When using an API key, control plane and data plane operations use the **key's org/project scope**, not the CLI's stored target context. The `pc target --show` output does not reflect what these operations actually use. API keys are scoped to a specific org and project and cannot access resources outside that scope. Admin API operations still use your user login or service account credentials (API keys can't authenticate Admin API calls). ## Managing target context ```bash theme={null} pc target --show # View current target pc target --clear # Clear target context ``` ### JSON mode and non-TTY environments Running `pc target --json` with no targeting flags returns the current target context as a JSON object. This is a local-state read — **no authentication is required**: ```bash theme={null} pc target --json ``` In non-TTY environments (CI/CD pipelines, shell pipes, scripts), JSON output is automatic — the same as passing `--json` explicitly. You do not need to add the flag in automation contexts. Use `--organization-id` and `--project-id` (instead of name flags) to set context reliably in scripts, since IDs are stable and unaffected by renames: ```bash theme={null} pc target --organization-id "org-abc123" --project-id "proj-xyz789" --json ``` # Pinecone SDKs overview Source: https://docs.pinecone.io/reference/pinecone-sdks Browse official Pinecone SDKs for Python, Node.js, Java, and Go, including the version mappings between SDK releases and API versions. ## Pinecone SDKs Official Pinecone SDKs provide convenient access to the [Pinecone APIs](/reference/api/introduction). ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and SDK versions are as follows: | | `2026-04` | `2025-10` | `2025-04` | `2025-01` | `2024-10` | `2024-07` | `2024-04` | | --------------------------------------------- | :---------- | :-------- | :-------- | :-------- | :-------- | :------------ | :-------- | | [Python SDK](/reference/sdks/python/overview) | v9.x | v8.x | v7.x | v6.x | v5.3.x | v5.0.x-v5.2.x | v4.x | | [Node.js SDK](/reference/sdks/node/overview) | v8.x | v7.x | v6.x | v5.x | v4.x | v3.x | v2.x | | [Java SDK](/reference/sdks/java/overview) | Coming soon | v6.x | v5.x | v4.x | v3.x | v2.x | v1.x | | [Go SDK](/reference/sdks/go/overview) | v6.x | v5.x | v4.x | v3.x | v2.x | v1.x | v0.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. The Java SDK targeting API version `2026-04` will be available soon. ## Limitations While Pinecone tracks read unit usage with decimal precision, the Pinecone API and SDKs round these values up to the nearest whole number in query, fetch, and list responses. For example, if a query uses 0.45 read units, the API and SDKs will report it as 1 read unit. For precise read unit reporting, see [index-level metrics](/guides/production/monitoring) or the organization-wide [Usage dashboard](/guides/manage-cost/monitor-usage-and-costs#monitor-organization-level-usage-and-costs). ## Community SDKs Find community-contributed SDKs for Pinecone. These libraries are not supported by Pinecone. * [Ruby SDK](https://github.com/ScotterC/pinecone) (contributed by [ScotterC](https://github.com/ScotterC)) * [Scala SDK](https://github.com/cequence-io/pinecone-scala) (contributed by [cequence-io](https://github.com/cequence-io)) * [PHP SDK](https://github.com/probots-io/pinecone-php) (contributed by [protobots-io](https://github.com/probots-io)) # Pinecone Go SDK Source: https://docs.pinecone.io/reference/sdks/go/overview Install and use the Pinecone Go SDK to manage indexes and namespaces, upsert vectors, run semantic search, and call the Admin and Inference APIs from Go. For installation instructions and usage examples, see the [Go SDK documentation](https://github.com/pinecone-io/go-pinecone). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/go-pinecone/issues). ## Requirements The Pinecone Go SDK requires a Go version with [modules](https://go.dev/wiki/Modules) support. ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and Go SDK versions are as follows: | API version | SDK version | | :---------- | :---------- | | `2026-04` | v6.x | | `2025-10` | v5.x | | `2025-04` | v4.x | | `2025-01` | v3.x | | `2024-10` | v2.x | | `2024-07` | v1.x | | `2024-04` | v0.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. ## Install To install the latest version of the [Go SDK](https://github.com/pinecone-io/go-pinecone), add a dependency to the current module: ```shell theme={null} go get github.com/pinecone-io/go-pinecone/v6/pinecone ``` To install a specific version of the Go SDK, run the following command: ```shell theme={null} go get github.com/pinecone-io/go-pinecone/v6/pinecone@ ``` To check your SDK version, run the following command: ```shell theme={null} go list -u -m all | grep go-pinecone ``` ## Upgrade Before upgrading to `v3.0.0` or later, update all relevant code to account for the breaking changes explained [here](/release-notes/2025#2025-02-07-4). Each major version carries its version number in the module path, so crossing a major requires updating the import path in every file that uses the SDK. For example, moving from `v4` to `v6` means changing: ```go theme={null} // before import "github.com/pinecone-io/go-pinecone/v4/pinecone" // after import "github.com/pinecone-io/go-pinecone/v6/pinecone" ``` Apart from the module path, `v5.0.0` and `v6.0.0` are backward compatible with the release lines before them. If you already have the Go SDK, upgrade to the latest version as follows: ```shell theme={null} go get -u github.com/pinecone-io/go-pinecone/v6/pinecone@latest ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance: ```Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) 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 manage organizations, projects, API keys, and [role-based access control](/guides/production/manage-rbac), initialize an `AdminClient` with [service account](/guides/organizations/manage-service-accounts) credentials instead: ```Go theme={null} package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } } ``` # Reference Source: https://docs.pinecone.io/reference/sdks/go/reference Reference documentation for the Pinecone Go SDK, including client setup, types, and methods for managing indexes and vector data operations. # OpenTelemetry support Source: https://docs.pinecone.io/reference/sdks/java/open-telemetry Monitor Pinecone Java SDK operations with OpenTelemetry metrics for client latency, server processing time, and errors via Prometheus. The Pinecone Java SDK provides built-in support for capturing per-operation response metadata, making it straightforward to monitor your Pinecone usage with [OpenTelemetry](https://opentelemetry.io/) or any other observability system. With this feature, you can track client-side latency, server processing time, network overhead, error rates, and more for every data plane operation your application makes. ## How it all fits together The SDK's observability support is designed to be flexible. You don't need to adopt the entire observability stack at once -- start simple and add layers as your needs grow. Here are the components involved and how they relate to each other: * **Pinecone Java SDK**: Exposes a `ResponseMetadataListener` callback, a plain Java interface with no external dependencies. At its simplest, you can log the metadata to the console. No additional tools required. * **[OpenTelemetry](https://opentelemetry.io/) (OTel)**: An open standard and SDK for producing structured telemetry data (metrics, traces, logs). If you want standardized metrics that follow [semantic conventions](https://opentelemetry.io/docs/specs/semconv/database/database-spans/), you add the OTel SDK and wire it to the listener. This is optional. * **OTel Collector**: A vendor-neutral service that receives telemetry from your app and forwards it to a storage backend. Optional -- many setups export directly from the app to a backend. * **Prometheus**: A time-series database that stores metrics, making them queryable over time. One popular storage option. * **Grafana**: A visualization and dashboarding tool that queries Prometheus (or other backends) and displays charts and alerts. One popular visualization option. A common setup chains these together: ``` Your App (OTel SDK) → OTel Collector → Prometheus (storage) → Grafana (visualization) ``` This is just one example pipeline. You can substitute Datadog, New Relic, or any OTel-compatible backend. You can also skip OTel entirely and use [Micrometer](#example-micrometerprometheus), custom logging, or any approach that suits your stack. ## Response metadata listener The Java SDK captures response metadata through a `ResponseMetadataListener` -- a functional interface you provide when building the Pinecone client. The listener is called after each data plane operation completes (whether it succeeds or fails), and receives a `ResponseMetadata` object containing timing, status, and context information. The SDK itself has no OpenTelemetry dependency. You bring your own observability library and decide what to do with the metadata. ### Supported operations The following data plane operations are instrumented, for both synchronous (`Index`) and asynchronous (`AsyncIndex`) usage: | Operation | Description | | --------- | -------------------------- | | `upsert` | Insert or update vectors | | `query` | Search for similar vectors | | `fetch` | Retrieve vectors by ID | | `update` | Update vector metadata | | `delete` | Delete vectors | ### Available metadata Each `ResponseMetadata` object provides the following fields: | Method | Description | OTel attribute | | ------------------------ | -------------------------------------------------- | ------------------------- | | `getOperationName()` | Operation type (e.g., `upsert`, `query`) | `db.operation.name` | | `getIndexName()` | Pinecone index name | `pinecone.index_name` | | `getNamespace()` | Namespace (empty string if default) | `db.namespace` | | `getServerAddress()` | Pinecone server host | `server.address` | | `getClientDurationMs()` | Total round-trip time in ms (always available) | -- | | `getServerDurationMs()` | Server processing time in ms (may be `null`) | -- | | `getNetworkOverheadMs()` | Client minus server duration in ms (may be `null`) | -- | | `getStatus()` | `"success"` or `"error"` | `status` | | `getGrpcStatusCode()` | Raw gRPC status code (e.g., `OK`, `UNAVAILABLE`) | `db.response.status_code` | | `getErrorType()` | Error category, or `null` if successful | `error.type` | Possible `errorType` values: `validation`, `connection`, `server`, `rate_limit`, `timeout`, `auth`, `not_found`, `unknown`. ### Recommended metrics If you're recording OTel metrics, the SDK example project uses these metric names, which follow [OTel semantic conventions for database clients](https://opentelemetry.io/docs/specs/semconv/database/database-spans/): | Metric | Type | Unit | Description | | ------------------------------------- | --------- | ---- | ------------------------------- | | `db.client.operation.duration` | Histogram | ms | Client-measured round-trip time | | `pinecone.server.processing.duration` | Histogram | ms | Server processing time | | `db.client.operation.count` | Counter | -- | Total number of operations | ## Quick start: Simple logging The simplest way to use the listener is to log the metadata directly. This requires no additional dependencies beyond the Pinecone SDK: ```java theme={null} import io.pinecone.clients.Pinecone; Pinecone client = new Pinecone.Builder("PINECONE_API_KEY") .withResponseMetadataListener(metadata -> { System.out.printf("Operation: %s | Client: %dms | Server: %sms | Network: %sms | Status: %s%n", metadata.getOperationName(), metadata.getClientDurationMs(), metadata.getServerDurationMs(), metadata.getNetworkOverheadMs(), metadata.getStatus()); }) .build(); ``` Once configured, every data plane operation automatically triggers the listener: ```java theme={null} Index index = client.getIndexConnection("my-index"); index.upsert("id-1", Arrays.asList(0.1f, 0.2f, 0.3f)); // Output: Operation: upsert | Client: 47ms | Server: 40ms | Network: 7ms | Status: success ``` ## Quick start: OpenTelemetry integration To record structured metrics with OpenTelemetry, add the OTel SDK dependencies and wire a metrics recorder to the listener. ### 1. Add dependencies Add the following to your `pom.xml`: ```xml theme={null} io.pinecone pinecone-client LATEST io.opentelemetry opentelemetry-sdk io.opentelemetry opentelemetry-sdk-metrics io.opentelemetry opentelemetry-exporter-otlp io.opentelemetry opentelemetry-bom 1.35.0 pom import ``` ### 2. Create a metrics recorder The SDK's [example project](https://github.com/pinecone-io/pinecone-java-client/tree/main/examples/java-otel-metrics) includes a reusable `PineconeMetricsRecorder` class you can copy into your project. It implements `ResponseMetadataListener` and records all three recommended metrics with proper OTel attributes: ```java theme={null} import io.opentelemetry.api.common.AttributeKey; import io.opentelemetry.api.common.Attributes; import io.opentelemetry.api.common.AttributesBuilder; import io.opentelemetry.api.metrics.LongCounter; import io.opentelemetry.api.metrics.LongHistogram; import io.opentelemetry.api.metrics.Meter; import io.pinecone.configs.ResponseMetadata; import io.pinecone.configs.ResponseMetadataListener; public class PineconeMetricsRecorder implements ResponseMetadataListener { private static final AttributeKey DB_SYSTEM = AttributeKey.stringKey("db.system"); private static final AttributeKey DB_OPERATION_NAME = AttributeKey.stringKey("db.operation.name"); private static final AttributeKey DB_NAMESPACE = AttributeKey.stringKey("db.namespace"); private static final AttributeKey PINECONE_INDEX_NAME = AttributeKey.stringKey("pinecone.index_name"); private static final AttributeKey SERVER_ADDRESS = AttributeKey.stringKey("server.address"); private static final AttributeKey STATUS = AttributeKey.stringKey("status"); private static final AttributeKey ERROR_TYPE = AttributeKey.stringKey("error.type"); private final LongHistogram clientDurationHistogram; private final LongHistogram serverDurationHistogram; private final LongCounter operationCounter; public PineconeMetricsRecorder(Meter meter) { this.clientDurationHistogram = meter.histogramBuilder("db.client.operation.duration") .setDescription("Duration of Pinecone operations from client perspective") .setUnit("ms") .ofLongs() .build(); this.serverDurationHistogram = meter.histogramBuilder("pinecone.server.processing.duration") .setDescription("Server processing time from x-pinecone-response-duration-ms header") .setUnit("ms") .ofLongs() .build(); this.operationCounter = meter.counterBuilder("db.client.operation.count") .setDescription("Total number of Pinecone operations") .setUnit("{operation}") .build(); } @Override public void onResponse(ResponseMetadata metadata) { AttributesBuilder attributesBuilder = Attributes.builder() .put(DB_SYSTEM, "pinecone") .put(DB_OPERATION_NAME, metadata.getOperationName()) .put(PINECONE_INDEX_NAME, metadata.getIndexName()) .put(SERVER_ADDRESS, metadata.getServerAddress()) .put(STATUS, metadata.getStatus()); String namespace = metadata.getNamespace(); if (namespace != null && !namespace.isEmpty()) { attributesBuilder.put(DB_NAMESPACE, namespace); } if (!metadata.isSuccess() && metadata.getErrorType() != null) { attributesBuilder.put(ERROR_TYPE, metadata.getErrorType()); } Attributes attributes = attributesBuilder.build(); clientDurationHistogram.record(metadata.getClientDurationMs(), attributes); Long serverDuration = metadata.getServerDurationMs(); if (serverDuration != null) { serverDurationHistogram.record(serverDuration, attributes); } operationCounter.add(1, attributes); } } ``` ### 3. Wire it into the Pinecone client Initialize the OTel SDK, create the recorder, and pass it to the Pinecone client builder: ```java theme={null} import io.opentelemetry.api.metrics.Meter; import io.opentelemetry.sdk.OpenTelemetrySdk; import io.opentelemetry.sdk.metrics.SdkMeterProvider; import io.opentelemetry.sdk.metrics.export.PeriodicMetricReader; import io.opentelemetry.exporter.otlp.metrics.OtlpGrpcMetricExporter; import io.pinecone.clients.Pinecone; // Set up OTel with OTLP exporter OtlpGrpcMetricExporter exporter = OtlpGrpcMetricExporter.builder() .setEndpoint("http://localhost:4317") .build(); SdkMeterProvider meterProvider = SdkMeterProvider.builder() .registerMetricReader(PeriodicMetricReader.builder(exporter).build()) .build(); OpenTelemetrySdk openTelemetry = OpenTelemetrySdk.builder() .setMeterProvider(meterProvider) .build(); // Create the metrics recorder Meter meter = openTelemetry.getMeter("pinecone.client"); PineconeMetricsRecorder recorder = new PineconeMetricsRecorder(meter); // Build the Pinecone client with the recorder Pinecone client = new Pinecone.Builder("PINECONE_API_KEY") .withResponseMetadataListener(recorder) .build(); // Use the client normally -- metrics are recorded automatically Index index = client.getIndexConnection("my-index"); index.upsert("id-1", Arrays.asList(0.1f, 0.2f, 0.3f)); index.query(3, Arrays.asList(0.1f, 0.2f, 0.3f)); ``` For a complete runnable example with Docker Compose, Prometheus, and Grafana, see the [java-otel-metrics example project](https://github.com/pinecone-io/pinecone-java-client/tree/main/examples/java-otel-metrics) in the SDK repository. ## Example: Micrometer/Prometheus If your application uses [Micrometer](https://micrometer.io/) (common in Spring Boot), you can wire the listener to Micrometer instead of the OTel SDK: ```java theme={null} import io.micrometer.core.instrument.MeterRegistry; import io.micrometer.core.instrument.Timer; import io.pinecone.clients.Pinecone; import java.util.concurrent.TimeUnit; Pinecone client = new Pinecone.Builder("PINECONE_API_KEY") .withResponseMetadataListener(metadata -> { Timer.builder("pinecone.client.duration") .tag("operation", metadata.getOperationName()) .tag("index", metadata.getIndexName()) .tag("status", metadata.getStatus()) .register(meterRegistry) .record(metadata.getClientDurationMs(), TimeUnit.MILLISECONDS); }) .build(); ``` ## Visualizing metrics Once your metrics are flowing to a backend, you can build dashboards to monitor your Pinecone operations. If you're using Prometheus and Grafana, here are some useful queries: **P50 and P95 client latency:** ```promql theme={null} histogram_quantile(0.5, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le)) histogram_quantile(0.95, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le)) ``` **P95 latency by operation type:** ```promql theme={null} histogram_quantile(0.95, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le, db_operation_name)) ``` **Operation count by type:** ```promql theme={null} sum by (db_operation_name) (db_client_operation_count_total) ``` ## Understanding the latency breakdown The `ResponseMetadata` object provides three timing values that help you pinpoint the source of latency issues: | Component | Method | What it measures | | ---------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | Client duration | `getClientDurationMs()` | Total round-trip time from request start to response completion. Always available. | | Server duration | `getServerDurationMs()` | Time the Pinecone backend spent processing the request. Extracted from the `x-pinecone-response-duration-ms` response header. May be `null`. | | Network overhead | `getNetworkOverheadMs()` | The difference: client duration minus server duration. Includes network latency, serialization, and deserialization. May be `null`. | Use these values to diagnose performance issues: * **High server duration**: The bottleneck is on the Pinecone backend. Consider optimizing your query (e.g., reducing `topK`, using metadata filters), or check the [Pinecone status page](https://status.pinecone.io/). * **High network overhead**: The bottleneck is in the network path between your application and Pinecone. Consider deploying your application closer to your index's cloud region, or check for network issues. ## Limitations * **Data plane operations only.** Control plane operations (e.g., creating or deleting indexes) are not currently instrumented. * **Bulk import operations** are not yet instrumented. * **Server duration may be unavailable.** The `getServerDurationMs()` method returns `null` if the `x-pinecone-response-duration-ms` header is not present in the response. * **Synchronous callback.** The listener is called synchronously after the gRPC response is received. Keep implementations lightweight and non-blocking to avoid adding latency to your operations. For heavy processing, queue the metadata for async handling. * **Exceptions are swallowed.** Exceptions thrown by the listener are logged but do not affect the operation result. ## Best practices * **Keep listeners lightweight.** Record metrics or enqueue work -- don't do I/O or heavy computation in the callback. * **Follow OTel semantic conventions.** Use the attribute names shown in the [recommended metrics](#recommended-metrics) table for interoperability with standard dashboards and tooling. * **Monitor both client and server duration.** Tracking both lets you separate Pinecone backend performance from network conditions. * **Set alerts on error rates.** Use the `status` and `error.type` attributes to build alerts for elevated error rates across operations. # Pinecone Java SDK Source: https://docs.pinecone.io/reference/sdks/java/overview Install and use the Pinecone Java SDK to manage indexes and namespaces, upsert vectors, run semantic search, and call the Admin and Inference APIs from Java. For installation instructions and usage examples, see the [Pinecone Java SDK documentation](https://github.com/pinecone-io/pinecone-java-client). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-java-client/issues). ## Requirements The Pinecone Java SDK requires Java 1.8 or later. ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and Java SDK versions are as follows: | API version | SDK version | | :---------- | :---------- | | `2025-04` | v5.x | | `2025-01` | v4.x | | `2024-10` | v3.x | | `2024-07` | v2.x | | `2024-04` | v1.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. ## Install To install the latest version of the [Java SDK](https://github.com/pinecone-io/pinecone-java-client), add a dependency to the current module: ```shell Java theme={null} # Maven io.pinecone pinecone-client 5.0.0 # Gradle implementation "io.pinecone:pinecone-client:5.0.0" ``` Alternatively, you can download the standalone uberjar [pinecone-client-4.0.0-all.jar](https://repo1.maven.org/maven2/io/pinecone/pinecone-client/4.0.0/pinecone-client-4.0.0-all.jar), which bundles the Pinecone SDK and all dependencies together. You can include this in your classpath like you do with any third-party JAR without having to obtain the `pinecone-client` dependencies separately. ## Upgrade Before upgrading to `v4.0.0`, update all relevant code to account for the breaking changes explained [here](/release-notes/2025#2025-02-07-3). If you are already using the Java SDK, upgrade the dependency in the current module to the latest version: ```shell Java theme={null} # Maven io.pinecone pinecone-client 5.0.0 # Gradle implementation "io.pinecone:pinecone-client:5.0.0" ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance: ```Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class InitializeClientExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); } } ``` ## Observability The Java SDK supports capturing per-operation response metadata for all data plane operations, including client-side latency, server processing time, network overhead, and error details. You can use this metadata with [OpenTelemetry](https://opentelemetry.io/), Micrometer, or any other observability system to monitor your Pinecone usage in production. For setup instructions and examples, see [OpenTelemetry support](/reference/sdks/java/open-telemetry). # Reference Source: https://docs.pinecone.io/reference/sdks/java/reference Reference documentation for the Pinecone Java SDK, including client setup, types, and methods for managing indexes and vector data operations. # Pinecone Node.js SDK Source: https://docs.pinecone.io/reference/sdks/node/overview Install and use the Pinecone Node.js and TypeScript SDK to manage indexes, upsert vectors, run semantic search, and call the Admin and Inference APIs. For installation instructions, usage examples, and reference information, see the [Pinecone Node.js SDK documentation](https://sdk.pinecone.io/typescript/). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-ts-client/issues). ## Requirements The Pinecone Node SDK requires TypeScript 4.1 or later and Node 18.x or later. ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and Node.js SDK versions are as follows: | API version | SDK version | | :---------- | :---------- | | `2026-04` | v8.x | | `2025-10` | v7.x | | `2025-04` | v6.x | | `2025-01` | v5.x | | `2024-10` | v4.x | | `2024-07` | v3.x | | `2024-04` | v2.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. ## Install To install the latest version of the [Node.js SDK](https://github.com/pinecone-io/pinecone-ts-client), written in TypeScript, run the following command: ```Shell theme={null} npm install @pinecone-database/pinecone ``` To check your SDK version, run the following command: ```Shell theme={null} npm list | grep @pinecone-database/pinecone ``` ## Upgrade If you already have the Node.js SDK, upgrade to the latest version as follows: ```Shell theme={null} npm install @pinecone-database/pinecone@latest ``` ## Initialize Once installed, you can import the library and then use an [API key](/guides/projects/manage-api-keys) to initialize a client instance: ```JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); ``` To manage organizations, projects, API keys, and [role-based access control](/guides/production/manage-rbac), initialize an `AdminClient` with [service account](/guides/organizations/manage-service-accounts) credentials instead. This requires v8.2.0 or later: ```JavaScript theme={null} import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); ``` You can also pass `clientId` and `clientSecret` directly to the constructor instead of setting environment variables. ## Proxy configuration If your network setup requires you to interact with Pinecone through a proxy, you can pass a custom `ProxyAgent` from the [`undici` library](https://undici.nodejs.org/#/). Below is an example of how to construct an `undici` `ProxyAgent` that routes network traffic through a [`mitm` proxy server](https://mitmproxy.org/) while hitting Pinecone's `/indexes` endpoint. The following strategy relies on Node's native [`fetch`](https://nodejs.org/docs/latest/api/globals.html#fetch) implementation, released in Node v16 and stabilized in Node v21. If you are running Node versions 18-21, you may experience issues stemming from the instability of the feature. There are currently no known issues related to proxying in Node v18+. ```JavaScript JavaScript theme={null} import { Pinecone, type PineconeConfiguration, } from '@pinecone-database/pinecone'; import { Dispatcher, ProxyAgent } from 'undici'; import * as fs from 'fs'; const cert = fs.readFileSync('path/to/mitmproxy-ca-cert.pem'); const client = new ProxyAgent({ uri: 'https://your-proxy.com', requestTls: { port: 'YOUR_PROXY_SERVER_PORT', ca: cert, host: 'YOUR_PROXY_SERVER_HOST', }, }); const customFetch = ( input: string | URL | Request, init: RequestInit | undefined ) => { return fetch(input, { ...init, dispatcher: client as Dispatcher, keepalive: true, # optional }); }; const config: PineconeConfiguration = { apiKey: 'YOUR_API_KEY', fetchApi: customFetch, }; const pc = new Pinecone(config); const indexes = async () => { return await pc.listIndexes(); }; indexes().then((response) => { console.log('My indexes: ', response); }); ``` # Reference Source: https://docs.pinecone.io/reference/sdks/node/reference Reference documentation for the Pinecone Node.js SDK, including client setup, types, and methods for managing indexes and vector data operations. # Pinecone Python SDK Source: https://docs.pinecone.io/reference/sdks/python/overview Install and use the Pinecone SDK for Pinecone Python SDK: auth, typed clients, and API operations. For installation instructions, usage examples, and. For installation instructions, usage examples, and reference information, see the [Pinecone Python SDK documentation](https://sdk.pinecone.io/python/). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-python-client/issues). The Pinecone Python SDK is distributed on PyPI using the package name `pinecone`. By default, the `pinecone` package has a minimal set of dependencies and interacts with Pinecone via HTTP requests. However, you can install the following extras to unlock additional functionality: * `pinecone[grpc]` adds dependencies on `grpcio` and related libraries needed to run data operations such as upserts and queries over [gRPC](https://grpc.io/) for a modest performance improvement. * `pinecone[asyncio]` adds a dependency on `aiohttp` and enables usage of `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). For more details, see [Async requests](#async-requests). ## Requirements The Pinecone Python SDK requires Python 3.9 or later. It has been tested with CPython versions from 3.9 to 3.13. ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and Python SDK versions are as follows: | API version | SDK version | | :---------- | :------------ | | `2025-04` | v7.x | | `2025-01` | v6.x | | `2024-10` | v5.3.x | | `2024-07` | v5.0.x-v5.2.x | | `2024-04` | v4.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. ## Install To install the latest version of the [Python SDK](https://github.com/pinecone-io/pinecone-python-client), run the following command: ```shell theme={null} # Install the latest version pip install pinecone # Install the latest version with gRPC extras pip install "pinecone[grpc]" # Install the latest version with asyncio extras pip install "pinecone[asyncio]" ``` To install a specific version of the Python SDK, run the following command: ```shell pip theme={null} # Install a specific version pip install pinecone== # Install a specific version with gRPC extras pip install "pinecone[grpc]"== # Install a specific version with asyncio extras pip install "pinecone[asyncio]"== ``` To check your SDK version, run the following command: ```shell pip theme={null} pip show pinecone ``` To use the [Inference API](/reference/api/introduction#inference), you must be on version 5.0.0 or later. ### Install the Pinecone Assistant Python plugin As of Python SDK v7.0.0, the `pinecone-plugin-assistant` package is included by default. It is only necessary to install the package if you are using a version of the Python SDK prior to v7.0.0. ```shell HTTP theme={null} pip install --upgrade pinecone pinecone-plugin-assistant ``` ## Upgrade Before upgrading to `v6.0.0`, update all relevant code to account for the breaking changes explained [here](https://github.com/pinecone-io/pinecone-python-client/blob/main/docs/upgrading.md). Also, make sure to upgrade using the `pinecone` package name instead of `pinecone-client`; upgrading with the latter will not work as of `v6.0.0`. If you already have the Python SDK, upgrade to the latest version as follows: ```shell theme={null} # Upgrade to the latest version pip install pinecone --upgrade # Upgrade to the latest version with gRPC extras pip install "pinecone[grpc]" --upgrade # Upgrade to the latest version with asyncio extras pip install "pinecone[asyncio]" --upgrade ``` ## Initialize Once installed, you can import the library and then use an [API key](/guides/projects/manage-api-keys) to initialize a client instance: ```Python HTTP theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` ```python gRPC theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` When [creating an index](/guides/index-data/create-an-index), import the `ServerlessSpec` or `PodSpec` class as well: ```Python Serverless index theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ) ) ``` ```Python Pod-based index theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import PodSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=PodSpec( environment="us-west-1-gcp", pod_type="p1.x1", pods=1 ) ) ``` ## Proxy configuration If your network setup requires you to interact with Pinecone through a proxy, you will need to pass additional configuration using optional keyword parameters: * `proxy_url`: The location of your proxy. This could be an HTTP or HTTPS URL depending on your proxy setup. * `proxy_headers`: Accepts a python dictionary which can be used to pass any custom headers required by your proxy. If your proxy is protected by authentication, use this parameter to pass basic authentication headers with a digest of your username and password. The `make_headers` utility from `urllib3` can be used to help construct the dictionary. **Note:** Not supported with Asyncio. * `ssl_ca_certs`: By default, the client will perform SSL certificate verification using the CA bundle maintained by Mozilla in the [`certifi`](https://pypi.org/project/certifi/) package. If your proxy is using self-signed certicates, use this parameter to specify the path to the certificate (PEM format). * `ssl_verify`: SSL verification is enabled by default, but it is disabled when set to `False`. It is not recommened to go into production with SSL verification disabled. ```python HTTP theme={null} from pinecone import Pinecone import urllib3 from urllib3.util import make_headers pc = Pinecone( api_key="YOUR_API_KEY", proxy_url='https://your-proxy.com', proxy_headers=make_headers(proxy_basic_auth='username:password'), ssl_ca_certs='path/to/cert-bundle.pem' ) ``` ```python gRPC theme={null} from pinecone.grpc import PineconeGRPC as Pinecone import urllib3 from urllib3.util import make_headers pc = Pinecone( api_key="YOUR_API_KEY", proxy_url='https://your-proxy.com', proxy_headers=make_headers(proxy_basic_auth='username:password'), ssl_ca_certs='path/to/cert-bundle.pem' ) ``` ```python asyncio theme={null} import asyncio from pinecone import PineconeAsyncio async def main(): async with PineconeAsyncio( api_key="YOUR_API_KEY", proxy_url='https://your-proxy.com', ssl_ca_certs='path/to/cert-bundle.pem' ) as pc: # Do async things await pc.list_indexes() asyncio.run(main()) ``` ## Async requests Pinecone Python SDK versions 6.0.0 and later provide `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). Asyncio support makes it possible to use Pinecone with modern async web frameworks such as [FastAPI](https://fastapi.tiangolo.com/), [Quart](https://quart.palletsprojects.com/en/latest/), and [Sanic](https://sanic.dev/en/), and should significantly increase the efficiency of running requests in parallel. Use the [`PineconeAsyncio`](https://sdk.pinecone.io/python/asyncio.html) class to create and manage indexes and the [`IndexAsyncio`](https://sdk.pinecone.io/python/asyncio.html#pinecone.db_data.IndexAsyncio) class to read and write index data. To ensure that sessions are properly closed, use the `async with` syntax when creating `PineconeAsyncio` and `IndexAsyncio` objects. ```python Manage indexes theme={null} # pip install "pinecone[asyncio]" import asyncio from pinecone import PineconeAsyncio, ServerlessSpec async def main(): async with PineconeAsyncio(api_key="YOUR_API_KEY") as pc: if not await pc.has_index(index_name): desc = await pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ), deletion_protection="disabled", tags={ "environment": "development" } ) asyncio.run(main()) ``` ```python Read and write index data theme={null} # pip install "pinecone[asyncio]" import asyncio from pinecone import Pinecone async def main(): pc = Pinecone(api_key="YOUR_API_KEY") async with pc.IndexAsyncio(host="INDEX_HOST") as idx: await idx.upsert_records( namespace="example-namespace", records=[ { "id": "1", "title": "The Great Gatsby", "author": "F. Scott Fitzgerald", "description": "The story of the mysteriously wealthy Jay Gatsby and his love for the beautiful Daisy Buchanan.", "year": 1925, }, { "id": "2", "title": "To Kill a Mockingbird", "author": "Harper Lee", "description": "A young girl comes of age in the segregated American South and witnesses her father's courageous defense of an innocent black man.", "year": 1960, }, { "id": "3", "title": "1984", "author": "George Orwell", "description": "In a dystopian future, a totalitarian regime exercises absolute control through pervasive surveillance and propaganda.", "year": 1949, }, ] ) asyncio.run(main()) ``` ## Query across namespaces Each query is limited to a single [namespace](/guides/index-data/indexing-overview#namespaces). However, the Pinecone Python SDK provides a `query_namespaces` utility method to run a query in parallel across multiple namespaces in an index and then merge the result sets into a single ranked result set with the `top_k` most relevant results. The `query_namespaces` method accepts most of the same arguments as `query` with the addition of a required `namespaces` parameter. When using the Python SDK without gRPC extras, to get good performance, it is important to set values for the `pool_threads` and `connection_pool_maxsize` properties on the index client. The `pool_threads` setting is the number of threads available to execute requests, while `connection_pool_maxsize` is the number of cached http connections that will be held. Since these tasks are not computationally heavy and are mainly i/o bound, it should be okay to have a high ratio of threads to cpus. The combined results include the sum of all read unit usage used to perform the underlying queries for each namespace. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index( name="docs-example", pool_threads=50, # <-- make sure to set these connection_pool_maxsize=50, # <-- make sure to set these ) query_vec = [ 0.1, ...] # an embedding vector with same dimension as the index combined_results = index.query_namespaces( vector=query_vec, namespaces=['ns1', 'ns2', 'ns3', 'ns4'], metric="cosine", top_k=10, include_values=False, include_metadata=True, filter={"genre": { "$eq": "comedy" }}, show_progress=False, ) for scored_vec in combined_results.matches: print(scored_vec) print(combined_results.usage) ``` When using the Python SDK with gRPC extras, there is no need to set the `connection_pool_maxsize` because grpc makes efficient use of open connections by default. ```python Python theme={null} from pinecone.grpc import PineconeGRPC pc = PineconeGRPC(api_key="YOUR_API_KEY") index = pc.Index( name="docs-example", pool_threads=50, # <-- make sure to set this ) query_vec = [ 0.1, ...] # an embedding vector with same dimension as the index combined_results = index.query_namespaces( vector=query_vec, namespaces=['ns1', 'ns2', 'ns3', 'ns4'], metric="cosine", top_k=10, include_values=False, include_metadata=True, filter={"genre": { "$eq": "comedy" }}, show_progress=False, ) for scored_vec in combined_results.matches: print(scored_vec) print(combined_results.usage) ``` ## Upsert from a dataframe To quickly ingest data when using the [Python SDK](/reference/sdks/python/overview), use the `upsert_from_dataframe` method. The method includes retry logic and`batch_size`, and is performant especially with Parquet file data sets. The following example upserts the `uora_all-MiniLM-L6-bm25` dataset as a dataframe. ```Python Python theme={null} from pinecone import Pinecone, ServerlessSpec from pinecone_datasets import list_datasets, load_dataset pc = Pinecone(api_key="API_KEY") dataset = load_dataset("quora_all-MiniLM-L6-bm25") pc.create_index( name="docs-example", dimension=384, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ) ) # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.upsert_from_dataframe(dataset.drop(columns=["blob"])) ``` # Reference Source: https://docs.pinecone.io/reference/sdks/python/reference Reference documentation for the Pinecone Python SDK, including client setup, types, and methods for managing indexes and vector data operations. # Spark-Pinecone connector Source: https://docs.pinecone.io/reference/tools/pinecone-spark-connector Pinecone data tools: Use the connector to efficiently create, ingest, and update vector embeddings at scale with Databricks and Pinecone. Use the [`spark-pinecone` connector](https://github.com/pinecone-io/spark-pinecone/) to efficiently create, ingest, and update [vector embeddings](https://www.pinecone.io/learn/vector-embeddings/) at scale with [Databricks and Pinecone](/integrations/databricks). ## Install the Spark-Pinecone connector 1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster). 2. Configure the library as follows: 1. Select **File path/S3** as the **Library Source**. 2. Enter the S3 URI for the Pinecone assembly JAR file: ``` s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar ``` Databricks platform users must use the Pinecone assembly jar listed above to ensure that the proper dependecies are installed. 3. Click **Install**. 1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster). 2. Configure the library as follows: 1. Select **File path/S3** as the **Library Source**. 2. Enter the S3 URI for the Pinecone assembly JAR file: ``` s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar ``` 3. Click **Install**. 1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster). 2. Configure the library as follows: 1. [Download the Pinecone assembly JAR file](https://repo1.maven.org/maven2/io/pinecone/spark-pinecone_2.12/1.1.0/). 2. Select **Workspace** as the **Library Source**. 3. Upload the JAR file. 4. Click **Install**. ## Batch upsert To batch upsert embeddings to Pinecone: ```python Python theme={null} from pyspark import SparkConf from pyspark.sql import SparkSession from pyspark.sql.types import StructType, StructField, ArrayType, FloatType, StringType, LongType # Your API key and index name api_key = "PINECONE_API_KEY" index_name = "PINECONE_INDEX_NAME" source_tag = "PINECONE_SOURCE_TAG" COMMON_SCHEMA = StructType([ StructField("id", StringType(), False), StructField("namespace", StringType(), True), StructField("values", ArrayType(FloatType(), False), False), StructField("metadata", StringType(), True), StructField("sparse_values", StructType([ StructField("indices", ArrayType(LongType(), False), False), StructField("values", ArrayType(FloatType(), False), False) ]), True) ]) # Initialize Spark spark = SparkSession.builder.getOrCreate() # Read the file and apply the schema df = spark.read \ .option("multiLine", value = True) \ .option("mode", "PERMISSIVE") \ .schema(COMMON_SCHEMA) \ .json("src/test/resources/sample.jsonl") # Show if the read was successful df.show() # Write the dataFrame to Pinecone in batches df.write \ .option("pinecone.apiKey", api_key) \ .option("pinecone.indexName", index_name) \ .option("pinecone.sourceTag", source_tag) \ .format("io.pinecone.spark.pinecone.Pinecone") \ .mode("append") \ .save() ``` ```scala Scala theme={null} import io.pinecone.spark.pinecone.{COMMON_SCHEMA, PineconeOptions} import org.apache.spark.SparkConf import org.apache.spark.sql.{SaveMode, SparkSession} object MainApp extends App { // Your API key and index name val apiKey = "PINECONE_API_KEY" val indexName = "PINECONE_INDEX_NAME" val sourceTag = "PINECONE_SOURCE_TAG" // Configure Spark to run locally with all available cores val conf = new SparkConf() .setMaster("local[*]") // Create a Spark session with the defined configuration val spark = SparkSession.builder().config(conf).getOrCreate() // Read the JSON file into a DataFrame, applying the COMMON_SCHEMA val df = spark.read .option("multiLine", value = true) .option("mode", "PERMISSIVE") .schema(COMMON_SCHEMA) .json("src/test/resources/sample.jsonl") // path to sample.jsonl // Define Pinecone options as a Map val pineconeOptions = Map( PineconeOptions.PINECONE_API_KEY_CONF -> apiKey, PineconeOptions.PINECONE_INDEX_NAME_CONF -> indexName, PineconeOptions.PINECONE_SOURCE_TAG_CONF -> sourceTag ) // Show if the read was successful df.show(df.count().toInt) // Write the DataFrame to Pinecone using the defined options in batches df.write .options(pineconeOptions) .format("io.pinecone.spark.pinecone.Pinecone") .mode(SaveMode.Append) .save() } ``` For a guide on how to set up batch upserts, refer to the [Databricks integration page](/integrations/databricks#setup-guide). ## Stream upsert To stream upsert embeddings to Pinecone: ```python Python theme={null} from pyspark.sql import SparkSession from pyspark.sql.types import StructType, StructField, ArrayType, FloatType, StringType, LongType import os # Your API key and index name api_key = "PINECONE_API_KEY" index_name = "PINECONE_INDEX_NAME" source_tag = "PINECONE_SOURCE_TAG" COMMON_SCHEMA = StructType([ StructField("id", StringType(), False), StructField("namespace", StringType(), True), StructField("values", ArrayType(FloatType(), False), False), StructField("metadata", StringType(), True), StructField("sparse_values", StructType([ StructField("indices", ArrayType(LongType(), False), False), StructField("values", ArrayType(FloatType(), False), False) ]), True) ]) # Initialize Spark session spark = SparkSession.builder \ .appName("StreamUpsertExample") \ .config("spark.sql.shuffle.partitions", 3) \ .master("local") \ .getOrCreate() # Read the stream of JSON files, applying the schema from the input directory lines = spark.readStream \ .option("multiLine", True) \ .option("mode", "PERMISSIVE") \ .schema(COMMON_SCHEMA) \ .json("path/to/input/directory/") # Write the stream to Pinecone using the defined options upsert = lines.writeStream \ .format("io.pinecone.spark.pinecone.Pinecone") \ .option("pinecone.apiKey", api_key) \ .option("pinecone.indexName", index_name) \ .option("pinecone.sourceTag", source_tag) \ .option("checkpointLocation", "path/to/checkpoint/dir") \ .outputMode("append") \ .start() upsert.awaitTermination() ``` ```scala Scala theme={null} import io.pinecone.spark.pinecone.{COMMON_SCHEMA, PineconeOptions} import org.apache.spark.SparkConf import org.apache.spark.sql.{SaveMode, SparkSession} object MainApp extends App { // Your API key and index name val apiKey = "PINECONE_API_KEY" val indexName = "PINECONE_INDEX_NAME" // Create a Spark session val spark = SparkSession.builder() .appName("StreamUpsertExample") .config("spark.sql.shuffle.partitions", 3) .master("local") .getOrCreate() // Read the JSON files into a DataFrame, applying the COMMON_SCHEMA from input directory val lines = spark.readStream .option("multiLine", value = true) .option("mode", "PERMISSIVE") .schema(COMMON_SCHEMA) .json("path/to/input/directory/") // Define Pinecone options as a Map val pineconeOptions = Map( PineconeOptions.PINECONE_API_KEY_CONF -> System.getenv("PINECONE_API_KEY"), PineconeOptions.PINECONE_INDEX_NAME_CONF -> System.getenv("PINECONE_INDEX"), PineconeOptions.PINECONE_SOURCE_TAG_CONF -> System.getenv("PINECONE_SOURCE_TAG") ) // Write the stream to Pinecone using the defined options val upsert = lines .writeStream .format("io.pinecone.spark.pinecone.Pinecone") .options(pineconeOptions) .option("checkpointLocation", "path/to/checkpoint/dir") .outputMode("append") .start() upsert.awaitTermination() } ``` ## Learn more * [Spark-Pinecone connector setup guide](/integrations/databricks#setup-guide) * [GitHub](https://github.com/pinecone-io/spark-pinecone) # Authentication Source: https://docs.pinecone.io/reference/api/authentication Pinecone API authentication guide covering API key generation, SDK client setup, and HTTP header configuration for authorized requests. All requests to [Pinecone APIs](/reference/api/introduction) must contain a valid [API key](/guides/production/security-overview#api-keys) for the target project. ## Get an API key [Create a new API key](https://app.pinecone.io/organizations/-/projects/-/keys) in the Pinecone console, or use the connect widget below to generate a key.
Copy your generated key: ``` PINECONE_API_KEY="{{YOUR_API_KEY}}" # This API key has ReadWrite access to all indexes in your project. ``` ## Initialize a client When using a [Pinecone SDK](/reference/pinecone-sdks), initialize a client object with your API key and then reuse the authenicated client in subsquent function calls. For example: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key='YOUR_API_KEY') # Creates an index using the API key stored in the client 'pc'. pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud='aws', region='us-east-1' ) ) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); // Creates an index using the API key stored in the client 'pc'. await pc.createIndex({ name: 'docs-example', dimension: 1536, metric: 'cosine', spec: { serverless: { cloud: 'aws', region: 'us-east-1' } } }) ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.IndexModel; import org.openapitools.db_control.client.model.DeletionProtection; public class CreateServerlessIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); // Creates an index using the API key stored in the client 'pc'. pc.createServerlessIndex("docs-example", "cosine", 1536, "aws", "us-east-1"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v3/pinecone" ) 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) } indexName := "docs-example" vectorType := "dense" dimension := int32(1536) metric := pinecone.Cosine deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: indexName, VectorType: &vectorType, Dimension: &dimension, Metric: &metric, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: &deletionProtection, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", err) } else { fmt.Printf("Successfully created serverless index: %v", idx.Name) } } ``` ```shell curl theme={null} curl -s "https://api.pinecone.io/indexes" \ -H "Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud":"aws", "region": "us-east-1" } } }' ``` ## Add headers to an HTTP request All HTTP requests to Pinecone APIs must contain an `Api-Key` header that specifies a valid [API key](/guides/production/security-overview#api-keys) and must be encoded as JSON with the `Content-Type: application/json` header. For example: ```shell curl theme={null} curl https://api.pinecone.io/indexes \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud":"aws", "region": "us-east-1" } } }' ``` ## Troubleshooting Older versions of Pinecone required you to initialize a client with an `init` method that takes both `api_key` and `environment` parameters, for example: ```python Python theme={null} # Legacy initialization import pinecone pc = pinecone.init( api_key="PINECONE_API_KEY", environment="PINECONE_ENVIRONMENT" ) ``` ```javascript JavaScript theme={null} // Legacy initialization import { Pinecone } from '@pinecone-database/pinecone'; const pineconeClient = new PineconeClient(); await pineconeClient.init({ apiKey: 'PINECONE_API_KEY', environment: 'PINECONE_ENVIRONMENT', }); ``` In more recent versions of Pinecone, this has changed. Initialization no longer requires an `init` step, and cloud environment is defined for each index rather than an entire project. Client initialization now only requires an `api_key` parameter, for example: ```python Python theme={null} # New initialization from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` ```javascript JavaScript theme={null} // New initialization import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); ``` If you are receiving errors about initialization, upgrade your [Pinecone SDK](/reference/pinecone-sdks) to the latest version, for example: ```shell Python theme={null} # Upgrade Pinecone SDK pip install pinecone --upgrade ``` ```shell JavaScript theme={null} # Upgrade Pinecone SDK npm install @pinecone-database/pinecone@latest ``` Also, note that some third-party tutorials and examples still reference the older initialization method. In such cases, follow the example above and the examples throughout the Pinecone documentation instead. # Pinecone Database limits Source: https://docs.pinecone.io/reference/api/database-limits Reference for Pinecone Database limits, covering upsert, query, fetch, delete, import, namespace, and rate limits for serverless indexes. This page describes different types of limits for Pinecone Database. **Looking for a specific limit?** * To compare monthly included usage by plan, start with [read units](#read-units-per-month-per-org), [write units](#write-units-per-month-per-org), and [model usage limits](#monthly-usage-limits). * If you received a `429` error, check [rate limits](#rate-limits), especially request-per-second limits for query, upsert, update, delete, fetch, and list. * For projects, users, indexes, namespaces, storage, backups, and collections, see [object limits](#object-limits). * For batch sizes, metadata filters, and identifier lengths, see [operation limits](#operation-limits) and [identifier limits](#identifier-limits). ## Rate limits Rate limits help protect your applications from misuse and maintain the health of our shared serverless infrastructure. These limits are designed to support typical production workloads while ensuring reliable performance for all users. **Most rate limits can be adjusted upon request.** If you need higher limits to scale your application, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. Pinecone is committed to supporting your growth and can often accommodate higher throughput requirements. Rate limits vary based on [pricing plan](https://www.pinecone.io/pricing/) and apply to [serverless indexes](/guides/index-data/indexing-overview) only. Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Data plane operations: request-per-second limits Pinecone enforces rate limits on the number of API requests per second at the namespace level for data plane operations (query, upsert, delete, and update). These limits provide protection against excessive request rates. #### Affected operations The following operations are subject to request-per-second rate limiting: | Operation | Scope | Limit | | --------- | ------------- | ----- | | Query | Per namespace | 100 | | Upsert | Per namespace | 100 | | Delete | Per namespace | 100 | | Update | Per namespace | 100 | #### Error response When you exceed the request-per-second limit, you'll receive an HTTP `429 - TOO_MANY_REQUESTS` response. The error message indicates which operation exceeded the limit and includes the namespace name and limit value. See the individual limit sections below for specific error message formats. #### How request-per-second limits work with limits on read and write units Request-per-second limits are enforced in addition to existing read unit and write unit limits. Requests must not exceed any applicable limits: * Index-level limits - read and write unit limits, per index * Namespace-level limits - read and write unit limits, per namespace * Request-per-second limits - requests per second, per namespace If any limit is exceeded, the request fails with a 429 error. #### Recommendations If you're hitting request-per-second limits: 1. Implement retry logic. Use exponential backoff to handle rate limit errors gracefully. See [Error Handling Guide](/guides/production/error-handling#implement-retry-logic). 2. Pace your requests. Add client-side rate limiting to stay under limits. 3. Consider [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes), which don't have request-per-second limits and provide dedicated capacity for high-throughput workloads. 4. If you need higher limits, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. ### All rate limits #### Monthly usage limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :---------------------------------------------------------------------------- | :------------- | :------------- | :------------- | :-------------- | | [Read units per month per org](#read-units-per-month-per-org) | 1,000,000 | 2,000,000 | Unlimited | Unlimited | | [Write units per month per org](#write-units-per-month-per-org) | 2,000,000 | 5,000,000 | Unlimited | Unlimited | | [Embedding tokens per month per model](#embedding-tokens-per-month-per-model) | 5,000,000 | 10,000,000 | Unlimited | Unlimited | | [Rerank requests per month per model](#rerank-requests-per-month-per-model) | Model-specific | Model-specific | Model-specific | Model-specific | #### Data operation throughput limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :------------------------------------------------------------------------------------------------------------ | :----------- | :----------- | :------------ | :-------------- | | [Upsert size per second per namespace](#upsert-size-per-second-per-namespace) | 50 MB | 50 MB | 50 MB | 50 MB | | [Query read units per second per index](#query-read-units-per-second-per-index) | 2,000 | 2,000 | 2,000 | 2,000 | | [Query requests per second per namespace](#query-requests-per-second-per-namespace) | 100 | 100 | 100 | 100 | | [Update records per second per namespace](#update-records-per-second-per-namespace) | 100 | 100 | 100 | 100 | | [Update requests per second per namespace](#update-requests-per-second-per-namespace) | 100 | 100 | 100 | 100 | | [Update by metadata requests per second per namespace](#update-by-metadata-requests-per-second-per-namespace) | 5 | 5 | 5 | 5 | | [Update by metadata requests per second per index](#update-by-metadata-requests-per-second-per-index) | 500 | 500 | 500 | 500 | | [Upsert requests per second per namespace](#upsert-requests-per-second-per-namespace) | 100 | 100 | 100 | 100 | | [Fetch requests per second per index](#fetch-requests-per-second-per-index) | 100 | 100 | 100 | 100 | | [List requests per second per index](#list-requests-per-second-per-index) | 200 | 200 | 200 | 200 | | [Describe index stats requests per second per index](#describe-index-stats-requests-per-second-per-index) | 100 | 100 | 100 | 100 | | [Delete requests per second per namespace](#delete-requests-per-second-per-namespace) | 100 | 100 | 100 | 100 | | [Delete records per second per namespace](#delete-records-per-second-per-namespace) | 5,000 | 5,000 | 5,000 | 5,000 | | [Delete records per second per index](#delete-records-per-second-per-index) | 5,000 | 5,000 | 5,000 | 5,000 | | [Delete by metadata requests per second per namespace](#delete-by-metadata-requests-per-second-per-namespace) | 5 | 5 | 5 | 5 | | [Delete by metadata requests per second per index](#delete-by-metadata-requests-per-second-per-index) | 500 | 500 | 500 | 500 | #### Model throughput limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :------------------------------------------------------------------------------ | :------------- | :------------- | :------------- | :-------------- | | [Embedding tokens per minute per model](#embedding-tokens-per-minute-per-model) | Model-specific | Model-specific | Model-specific | Model-specific | | [Rerank requests per minute per model](#rerank-requests-per-minute-per-model) | Model-specific | Model-specific | Model-specific | Model-specific | ### Read units per month per org | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 1,000,000 | 2,000,000 | Unlimited | Unlimited | [Read units](/guides/manage-cost/understanding-cost#read-units) measure the compute, I/O, and network resources used by [fetch](/guides/manage-data/fetch-data), [query](/guides/search/search-overview), and [list](/guides/manage-data/list-record-ids) requests to serverless indexes. When you reach the monthly read unit limit for an organization, fetch, query, and list requests to serverless indexes in the organization will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached your read unit limit for the current month limit. To continue reading data, upgrade your plan. ``` To continue reading from serverless indexes in the organization, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). To check how close you are to the monthly read unit limit for your organization, do the following: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select the project. 3. Select any index in the project. 4. Look under **Usage**. Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Write units per month per org | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 2,000,000 | 5,000,000 | Unlimited | Unlimited | [Write units](/guides/manage-cost/understanding-cost#write-units) measure the storage and compute resources used by [upsert](/guides/index-data/upsert-data), [update](/guides/manage-data/update-data), and [delete](/guides/manage-data/delete-data) requests to serverless indexes. When you reach the monthly write unit limit for an organization, upsert, update, and delete requests to serverless indexes in the organization will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached your write unit limit for the current month. To continue writing data, upgrade your plan. ``` To continue writing data to serverless indexes in the organization, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). To check how close you are to the monthly write unit limit for your organization, do the following: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select the project. 3. Select any index in the project. 4. Look under **Usage**. ### Upsert size per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 50 MB | 50 MB | 50 MB | 50 MB | When you reach the per second [upsert](/guides/index-data/upsert-data) size for a namespace in an index, additional upserts will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max upsert size limit per second for index . Pace your upserts or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Query read units per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 2,000 | 2,000 | 2,000 | 2,000 | Pinecone measures [query](/guides/search/search-overview) usage in [read units](/guides/manage-cost/understanding-cost#read-units). When you reach the per second limit for queries across all namespaces in an index, additional queries will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max query read units per second for index . Pace your queries or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). To check how many read units a query consumes, [check the query response](/guides/manage-cost/monitor-usage-and-costs#read-units). Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Query requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [query](/guides/search/search-overview) limit for a namespace in an index, additional queries will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the query QPS limit for namespace {namespace_name} ({limit} QPS). Pace your queries, consider Dedicated Read Nodes for your index, or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Update records per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [update](/guides/manage-data/update-data) limit for a namespace in an index, additional updates will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max update records per second for namespace . Pace your update requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Update requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [update](/guides/manage-data/update-data) request limit for a namespace in an index, additional update requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the update QPS limit for namespace {namespace_name} ({limit} QPS). Pace your update requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). If you need to update most of the records in a large namespace, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) for help creating an export to enable a faster and more cost-effective approach. ### Update by metadata requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5 | 5 | 5 | 5 | When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit for a namespace in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max update by metadata requests per second for namespace . Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Update by metadata requests per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 500 | 500 | 500 | 500 | When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit across all namespaces in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max update by metadata requests per second for index . Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Upsert requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [upsert](/guides/index-data/upsert-data) request limit for a namespace in an index, additional upsert requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the upsert QPS limit for namespace {namespace_name} ({limit} QPS). Pace your upsert requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Fetch requests per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [fetch](/guides/manage-data/fetch-data) limit across all namespaces in an index, additional fetch requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max fetch requests per second for index . Pace your fetch requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### List requests per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 200 | 200 | 200 | 200 | When you reach the per second [list](/guides/manage-data/list-record-ids) limit across all namespaces in an index, additional list requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max list requests per second for index . Pace your list requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Indexes built on [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Describe index stats requests per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [describe index stats](/reference/api/2024-10/data-plane/describeindexstats) limit across all namespaces in an index, additional describe index stats requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max describe_index_stats requests per second for index . Pace your describe_index_stats requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 100 | 100 | 100 | When you reach the per second [delete](/guides/manage-data/delete-data) request limit for a namespace in an index, additional delete requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the delete QPS limit for namespace {namespace_name} ({limit} QPS). Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete records per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5000 | 5000 | 5000 | 5000 | When you reach the per second [delete](/guides/manage-data/delete-data) limit for a namespace in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete records per second for namespace . Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete records per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5000 | 5000 | 5000 | 5000 | When you reach the per second [delete](/guides/manage-data/delete-data) limit across all namespaces in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete records per second for index . Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete by metadata requests per second per namespace | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5 | 5 | 5 | 5 | When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit for a namespace in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete by metadata requests per second for namespace . Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete by metadata requests per second per index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 500 | 500 | 500 | 500 | When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit across all namespaces in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete by metadata requests per second for index . Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Embedding tokens per minute per model | Embedding model | Input type | Starter plan | Builder plan | Standard plan | Enterprise plan | | :--------------------------- | :--------- | :----------- | :----------- | :------------ | :-------------- | | `llama-text-embed-v2` | Passage | 250,000 | 250,000 | 1,000,000 | 1,000,000 | | | Query | 50,000 | 50,000 | 250,000 | 250,000 | | `multilingual-e5-large` | Passage | 250,000 | 250,000 | 1,000,000 | 1,000,000 | | | Query | 50,000 | 50,000 | 250,000 | 250,000 | | `pinecone-sparse-english-v0` | Passage | 250,000 | 250,000 | 3,000,000 | 3,000,000 | | | Query | 250,000 | 250,000 | 3,000,000 | 3,000,000 | When you reach the per minute token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max embedding tokens per minute () model ''' and input type '' for the current project. To increase this limit, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). Otherwise, you can handle this limit by [implementing retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). ### Embedding tokens per month per model | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5,000,000 | 10,000,000 | Unlimited | Unlimited | When you reach the monthly token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the embedding token limit () for model for the current month. To continue using this model, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Rerank requests per minute per model | Reranking model | Starter plan | Builder plan | Standard plan | Enterprise plan | | :--------------------- | :------------ | :------------ | :------------ | :-------------- | | `cohere-rerank-4-fast` | Not available | Not available | 300 | 300 | | `cohere-rerank-3.5` | Not available | Not available | 300 | 300 | | `bge-reranker-v2-m3` | 60 | 60 | 60 | 60 | | `pinecone-rerank-v0` | 60 | Not available | 60 | 60 | When you reach the per minute request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max rerank requests per minute () for model '' for the current project. To increase this limit, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Rerank requests per month per model | Reranking model | Starter plan | Builder plan | Standard plan | Enterprise plan | | :--------------------- | :------------ | :------------ | :------------ | :-------------- | | `cohere-rerank-4-fast` | Not available | Not available | Unlimited | Unlimited | | `cohere-rerank-3.5` | Not available | Not available | Unlimited | Unlimited | | `bge-reranker-v2-m3` | 500 | 1,000 | Unlimited | Unlimited | | `pinecone-rerank-v0` | 500 | Not available | Unlimited | Unlimited | When you reach the monthly request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the rerank request limit () for model for the current month. To continue using this model, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Inference requests per second or minute, per project | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :---------------------------- | :----------- | :----------- | :------------ | :-------------- | | Inference requests per second | 100 | 100 | 100 | 100 | | Inference requests per minute | 2000 | 2000 | 2000 | 2000 | When you reach the per second or per minute request limit, inference requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max inference requests per second () for the current project. ``` This error indicates per second or per minute, as applicable. To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). ## Object limits Object limits are restrictions on the number or size of objects in Pinecone. Object limits vary based on [pricing plan](https://www.pinecone.io/pricing/). | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :----------------------------------------------------------------------------- | :----------- | :----------- | :------------ | :-------------- | | [Projects per organization](#projects-per-organization) | 1 | 5 | 20 | 100 | | [Users per organization](#users-per-organization) | 2 | 5 | Unlimited | Unlimited | | [Serverless indexes per project](#serverless-indexes-per-project) 1 | 5 | 10 | 20 | 200 | | [Serverless index storage per org](#serverless-index-storage-per-org) | 2 GB | 10 GB | N/A | N/A | | [Namespaces per serverless index](#namespaces-per-serverless-index) | 100 | 1,000 | 100,000 | 100,000 | | [Serverless backups per project](#serverless-backups-per-project) | N/A | N/A | 500 | 1000 | | [Collections per project](#collections-per-project) | 100 | N/A | N/A | N/A | 1 On the Starter plan, all serverless indexes must be in the `us-east-1` region of AWS. Builder, Standard, and Enterprise plans can create indexes in any [supported region](/guides/index-data/create-an-index#cloud-regions).
### Projects per organization | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 1 | 5 | 20 | 100 | When you reach this quota for an organization, trying to [create projects](/guides/projects/create-a-project) will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max projects allowed in organization . To add more projects, upgrade your plan. ``` To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Users per organization | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 2 | 5 | Unlimited | Unlimited | When you reach this quota for an organization, trying to add users to the organization will fail. To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Serverless indexes per project | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 5 | 10 | 20 | 200 | When you reach this quota for a project, trying to [create serverless indexes](/guides/index-data/create-an-index#create-a-serverless-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max serverless indexes allowed in project . Use namespaces to partition your data into logical groups, or upgrade your plan to add more serverless indexes. ``` To stay under this quota, consider using [namespaces](/guides/index-data/create-an-index#namespaces) instead of creating multiple indexes. Namespaces let you partition your data into logical groups within a single index. This approach not only helps you stay within index limits, but can also improve query performance and lower costs by limiting searches to relevant data subsets. To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Serverless index storage per org This limit applies to organizations on the Starter and Builder plans only. | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 2 GB | 10 GB | N/A | N/A | When you've reached this quota for an organization, updates and upserts into serverless indexes will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max storage allowed for organization . To update or upsert new data, delete records or upgrade your plan. ``` To continue writing data into your serverless indexes, [delete records](/guides/manage-data/delete-data) to bring your organization under the limit or [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Namespaces per serverless index | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | 1,000 | 100,000 | 100,000 | When you reach this quota for a serverless index, trying to [upsert records into a new namespace](/guides/index-data/upsert-data) in the index will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max namespaces allowed in serverless index . To add more namespaces, upgrade your plan. ``` To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). [Namespaces per serverless index](/reference/api/database-limits#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](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Serverless backups per project | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | N/A | N/A | 500 | 1000 | Backups are not available on the Starter or Builder plans. On the Standard and Enterprise plans, when you reach this quota for a project, trying to [create serverless backups](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Backup failed to create. Quota for number of backups per index exceeded. ``` ### Collections per project | Starter plan | Builder plan | Standard plan | Enterprise plan | | ------------ | ------------ | ------------- | --------------- | | 100 | N/A | N/A | N/A | When you reach this quota for a project, trying to [create collections](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max collections allowed in project . To add more collections, upgrade your plan. ``` To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ## Operation limits Operation limits are restrictions on the size, number, or other characteristics of operations in Pinecone. Operation limits are fixed and do not vary based on pricing plan. ### Upsert limits | Metric | Limit | | :----------------------------------------------------------------- | :------------------------------------------------------------ | | Max [batch size](/guides/index-data/upsert-data#upsert-in-batches) | 2 MB or 1000 records with vectors
96 records with text | | Max documents per upsert request | 1000 | | Max document upsert request size | 2 MB | | Max document size | 2 MB | | Max `full_text_search` string fields per schema | 100 | | Max size per `full_text_search` string field | 100 KB | | Max tokens per `full_text_search` string field | 10,000 | | Max bytes per token | 256 bytes | | Max filterable metadata size per document | 40 KB | | Max length for a record ID | 512 characters | | Max dimensionality for dense vectors | 20,000 | | Max non-zero values for sparse vectors | 2048 | | Max dimensionality for sparse vectors | 4.2 billion | The 40 KB filterable metadata limit does not apply to `full_text_search` text fields. ### Import limits If your import exceeds these limits, you'll get an error specifying the limit exceeded. See [Troubleshooting](/guides/index-data/import-data#troubleshooting) for details. | Metric | Limit | | :-------------------------------------------- | :-------- | | Max namespaces per import | 10,000 | | Max total input data size (on-demand indexes) | 1 TB | | Max total input data size (DRN indexes) | Unlimited | | Max files per import | 100,000 | | Max size per file | 10 GB | The total input data size limit does not apply to indexes with [dedicated read nodes](/guides/index-data/dedicated-read-nodes). Bulk import supports indexes without a schema definition (Parquet files) and indexes with document schemas ([JSONL files](/guides/search/full-text-search#bulk-import)). Semantic-text (auto-embedded) fields are not yet supported in document schemas. ### Query limits | Metric | Limit | | :---------------- | :----- | | Max `top_k` value | 10,000 | | Max result size | 4MB | The query result size is affected by the dimension of the dense vectors and whether or not dense vector values and metadata are included in the result. If a query fails due to exceeding the 4MB result size limit, choose a lower `top_k` value, or use `include_metadata=False` or `include_values=False` to exclude metadata or values from the result. For better performance, especially with higher `top_k` values, avoid including vector values unless you need them. ### Fetch limits **Fetch by ID limits:** | Metric | Limit | | :------------------------------- | :---- | | Max record IDs per fetch request | 1,000 | **Fetch by metadata limits:** | Metric | Limit | | :----------------------- | :---------------------------------- | | Max records per response | 10,000 | | Max response size | 4 MB | | Max request rate | 5 requests per second per namespace | To retrieve more than 10,000 matching records, paginate through results using the `paginationToken` parameter. See [Fetch records by metadata](/guides/manage-data/fetch-data#fetch-records-by-metadata). ### Delete limits | Metric | Limit | | :-------------------------------- | :---- | | Max record IDs per delete request | 1,000 | ### Metadata filter limits The following limits apply to [metadata filter expressions](/guides/search/filter-by-metadata#metadata-filter-expressions) used in query, delete, update, and fetch operations. | Limit | Value | Description | | :------------------------------------------ | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Maximum values per `$in` or `$nin` operator | 10,000 | Each `$in` or `$nin` operator accepts up to 10,000 values in its array. This limit applies per operator—if you have multiple `$in` operators in a single filter, each is independently limited to 10,000 values. | When you exceed this limit, the request will fail and return a `400 - BAD_REQUEST` error. #### Rationale Large `$in` operators can impact query performance and cost. Filters with thousands of values increase request payload size and end-to-end latency. Additionally, using large filters typically indicates a shared namespace architecture, which increases query costs—queries scan the entire namespace regardless of filters. #### Alternative approaches If you need to filter by more than 10,000 values, consider these alternatives: * **Use namespaces for tenant isolation**: Instead of filtering by tenant IDs within a single namespace, create separate namespaces for each tenant or tenant group. This can also reduce query costs. See [Design for multi-tenancy](/guides/index-data/data-modeling#design-for-multi-tenancy). * **Use broader access control groups**: Instead of filtering by individual user IDs, filter by organization, project, or role. This reduces the number of values in your `$in` filter. See [Design for multi-tenancy](/guides/index-data/data-modeling#use-access-control-groups-instead-of-individual-ids). * **Post-filter client-side**: Retrieve a larger top K without filtering (for example, top 1000), then filter results client-side. * **Run multiple queries**: Split your filter into multiple queries with smaller `$in` operators and combine the results client-side. To avoid hitting this limit in production, validate the size of your `$in` and `$nin` arrays in your application code before making the request to Pinecone. ## Identifier limits An identifier is a string of characters used to identify "named" [objects in Pinecone](/guides/get-started/concepts). The following Pinecone objects use strings as identifiers: | Object | Field | Max # characters | Allowed characters | | --------------------------------------------------------- | ----------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | [Organization](/guides/get-started/concepts#organization) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Project](/guides/get-started/concepts#project) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Index](/guides/get-started/concepts#index) | `name` | 45 |
  • `a-z`, `0-9`, and `-`
  • Must be lowercase
  • Cannot start or end with `-`
  • Cannot be empty
| | [Namespace](/guides/get-started/concepts#namespace) | `namespace` | 512 |
  • ASCII except `\0`
  • For the default namespace, use `""` (or `"__default__"`, in API versions `2025-04` and later)
| | [Record](/guides/get-started/concepts#record) | `id` | 512 |
  • ASCII except `\0`
  • Cannot be empty
| # Errors Source: https://docs.pinecone.io/reference/api/errors Pinecone REST API: Pinecone uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the range. Pinecone uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that failed given the information provided, and codes in the `5xx` range indicate an error with Pinecone's servers. For guidance on handling errors in production, see [Error handling](/guides/production/error-handling). ## 200 - OK The request succeeded. ## 201 - CREATED The request succeeded and a new resource was created. ## 202 - NO CONTENT The request succeeded, but there is no content to return. ## 400 - INVALID ARGUMENT The request failed due to an invalid argument. ## 401 - UNAUTHENTICATED The request failed due to a missing or invalid [API key](/guides/projects/understanding-projects#api-keys). ## 402 - PAYMENT REQUIRED The request failed due to delinquent payment or account deactivation for non-payment. See [Account deactivation for non-payment](/guides/organizations/manage-billing/non-payment-account-deactivation). ## 403 - FORBIDDEN The request failed due to an exceeded [quota](/reference/api/database-limits#object-limits) or [index deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection). ## 404 - NOT FOUND The request failed because the resource was not found. ## 409 - ALREADY EXISTS The request failed because the resource already exists. ## 412 - FAILED PRECONDITIONS The request failed due to preconditions not being met. | ## 422 - UNPROCESSABLE ENTITY The request failed because the server was unable to process the contained instructions. ## 429 - TOO MANY REQUESTS The request was [rate-limited](/reference/api/database-limits#rate-limits). [Implement retry logic with exponential backoff](/guides/production/error-handling#handle-rate-limits-429) to handle this error. ## 500 - UNKNOWN An internal server error occurred. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. ## 502 - BAD GATEWAY The API gateway received an invalid response from a backend service. This is typically a temporary error. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. ## 503 - UNAVAILABLE The server is currently unavailable. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. ## 504 - GATEWAY TIMEOUT The API gateway did not receive a timely response from the backend server. This can occur due to slow requests or backend processing delays. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. # API reference Source: https://docs.pinecone.io/reference/api/introduction Pinecone API reference overview for Database, Inference, and Admin endpoints with supported SDKs including Python, Node.js, Java, and Go. Pinecone's APIs let you interact programmatically with your Pinecone account. [SDK versions](/reference/pinecone-sdks#sdk-versions) are pinned to specific API versions. ## Database Use the Database API to store and query records in [Pinecone Database](/guides/get-started/quickstart). The following Pinecone SDKs support the Database API: ## Inference Use the Inference API to generate vector embeddings and rerank results using [embedding models](/guides/index-data/create-an-index#embedding-models) and [reranking models](/guides/search/rerank-results#reranking-models) hosted on Pinecone's infrastructure. There are two ways to use the Inference API: * As a standalone service, through the [Rerank documents](/reference/api/latest/inference/rerank) and [Generate vectors](/reference/api/latest/inference/generate-embeddings) endpoints. * As an integrated part of database operations, through the [Create an index with integrated embedding](/reference/api/latest/control-plane/create_for_model), [Upsert text](/reference/api/latest/data-plane/upsert_records), and [Search with text](/reference/api/latest/data-plane/search_records) endpoints. The following Pinecone SDKs support using the Inference API: # Known limitations Source: https://docs.pinecone.io/reference/api/known-limitations Known limitations and feature restrictions for Pinecone indexes, including upsert consistency, metadata rules, and serverless caveats. This page describes known limitations and feature restrictions in Pinecone. ## General * [Upserts](/guides/index-data/upsert-data) * Pinecone is eventually consistent, so there can be a slight delay before upserted records are available to query. After upserting records, use the [`describe_index_stats`](/reference/api/2024-10/data-plane/describeindexstats) operation to check if the current vector count matches the number of records you expect, although this method may not work for pod-based indexes with multiple replicas. * Only indexes using the [dotproduct distance metric](/guides/index-data/indexing-overview#dotproduct) support querying sparse-dense vectors. Upserting, updating, and fetching sparse-dense vectors in indexes with a different distance metric will succeed, but querying will return an error. * Indexes created before February 22, 2023 do not support sparse vectors. * [Metadata](/guides/index-data/upsert-data#upsert-with-metadata-filters) * Null metadata values aren't supported. Instead of setting a key to `null`, remove the key from the metadata payload. * Nested JSON objects are not supported. ## Serverless indexes Serverless indexes do not support the following features: * [Filtering index statistics by metadata](/reference/api/2024-10/data-plane/describeindexstats) * [Private endpoints](/guides/production/configure-private-endpoints) * This feature is available on AWS only. # API versioning Source: https://docs.pinecone.io/reference/api/versioning Pinecone REST API: Pinecone's APIs are versioned to ensure that your applications continue to work as expected as the platform evolves. Pinecone's APIs are versioned to ensure that your applications continue to work as expected as the platform evolves. Versions are named by release date in the format `YYYY-MM`, for example, `2025-10`. ## Release schedule On a quarterly basis, Pinecone releases a new **stable** API version as well as a **release candidate** of the next stable version. * **Stable:** Each stable version remains unchanged and supported for a minimum of 12 months. Since stable versions are released every 3 months, this means you have at least 9 months to test and migrate your app to the newest stable version before support for the previous version is removed. * **Release candidate:** The release candidate gives you insight into the upcoming changes in the next stable version. It is available for approximately 3 months before the release of the stable version and can include new features, improvements, and [breaking changes](#breaking-changes). Below is an example of Pinecone's release schedule: ## Specify an API version When using the API directly, it is important to specify an API version in your requests. If you don't, requests default to the oldest supported stable version. Once support for that version ends, your requests will default to the next oldest stable version, which could include breaking changes that require you to update your integration. To specify an API version, set the `X-Pinecone-Api-Version` header to the version name. For example, to use the latest stable version (`2026-04`) to describe an index, set the `X-Pinecone-Api-Version` header: ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/indexes/movie-recommendations" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-04" ``` To use an older version, specify that version instead. ## SDK versions Official [Pinecone SDKs](/reference/pinecone-sdks) provide convenient access to Pinecone APIs. SDK versions are pinned to specific API versions. When a new API version is released, a new version of the SDK is also released. For the mapping between SDK and API versions, see [SDK versions](/reference/pinecone-sdks#sdk-versions). ## Breaking changes Breaking changes are changes that can potentially break your integration with a Pinecone API. Breaking changes include: * Removing an entire operation * Removing or renaming a parameter * Removing or renaming a response field * Adding a new required parameter * Making a previously optional parameter required * Changing the type of a parameter or response field * Removing enum values * Adding a new validation rule to an existing parameter * Changing authentication or authorization requirements ## Non-breaking changes Non-breaking changes are additive and should not break your integration. Additive changes include: * Adding an operation * Adding an optional parameter * Adding an optional request header * Adding a response field * Adding a response header * Adding enum values ## Get updates To ensure you always know about upcoming API changes, follow the [Release notes](/release-notes/). # CLI authentication Source: https://docs.pinecone.io/reference/cli/authentication Authenticate the Pinecone CLI using user login, service accounts, or API keys, including auth priority and Admin API access rules. This document describes how to authenticate the Pinecone CLI to manage your Pinecone resources. ## Authentication methods | Method | Admin API | Control/data plane | Best for | | ----------------------------------- | --------- | ------------------ | -------------------------------- | | [User login](#user-login) | ✅ | ✅ | Interactive use | | [Service account](#service-account) | ✅ | ✅ | Automation with Admin API access | | [API key](#api-key) | ❌ | ✅ | Simple automation, CI/CD | ### User login Authenticate through a web browser. The token refreshes automatically and stays valid for up to 120 days (re-auth required after 30 days of inactivity). ```bash theme={null} pc auth login ``` The CLI auto-targets your default organization and its first project. Change with `pc target -o "my-org" -p "my-project"`. ### Service account Authenticate with credentials from a [service account](/guides/organizations/manage-service-accounts). ```bash theme={null} pc auth configure --client-id "ID" --client-secret "SECRET" # Or via environment variables export PINECONE_CLIENT_ID="your-client-id" export PINECONE_CLIENT_SECRET="your-client-secret" ``` The CLI auto-targets the service account's organization. For projects: auto-selects if one exists, prompts if multiple exist, or set manually with `pc target -p "my-project"`. ### API key Authenticate with an [API key](/guides/projects/manage-api-keys). API keys can't access the Admin API. ```bash theme={null} pc auth configure --api-key "YOUR_API_KEY" # Or via environment variable export PINECONE_API_KEY="your-api-key" ``` API keys are scoped to a specific project. When set, control/data plane operations use the **key's project**, ignoring any [target context](/reference/cli/target-context) you've set. ## Auth priority When multiple credentials exist, the CLI chooses based on operation type. Within each credential type, environment variables take precedence over stored configuration. **Control/data plane operations:** 1. API key 2. User login token (via [managed keys](#managed-keys)) 3. Service account (via [managed keys](#managed-keys)) **Admin API operations:** 1. User login token 2. Service account User login and service account are mutually exclusive when configured via CLI commands—each clears the other. However, service account env vars don't clear a stored user login token. **Example scenarios:** * If `PINECONE_API_KEY` is set, the CLI uses it for control/data plane operations, regardless of any stored API key. * If you're logged in via `pc auth login` and also have `PINECONE_CLIENT_ID`/`PINECONE_CLIENT_SECRET` set, the user login token is used for everything—the service account env vars are ignored. * If you have an API key configured and are also logged in, the API key is used for control/data plane operations, but user login is used for Admin API operations (since API keys can't access Admin API). ## Managed keys When using user login or service account (without a default API key), the CLI automatically creates and manages API keys for control/data plane operations. This happens transparently on first use. * **Stored locally:** `~/.config/pinecone/secrets.yaml` (permissions 0600) * **Stored remotely:** Visible in console as `pinecone-cli-{id}` with origin `cli_created` ```bash theme={null} # List locally tracked managed keys pc auth local-keys list # Delete managed keys (local + remote) pc auth local-keys prune # Delete only CLI-created managed keys pc auth local-keys prune --origin cli # Delete only user-created managed keys pc auth local-keys prune --origin user # Delete a specific API key by ID pc api-key delete --id "KEY_ID" ``` When you run `pc api-key create --store` for a project that already has a CLI-created managed key, the CLI automatically deletes the old remote key before storing the new one. ## Logging out ```bash theme={null} pc auth logout ``` Clears all local auth data: tokens, credentials, API keys, managed keys, and [target context](/reference/cli/target-context). `pc auth logout` doesn't delete managed keys from Pinecone's servers. Run `pc auth local-keys prune` first for full cleanup. ## Local storage Auth data is stored in `~/.config/pinecone/` with 0600 permissions: | File | Contents | | -------------- | ---------------------------------------------------------------- | | `secrets.yaml` | OAuth token, service account credentials, API keys, managed keys | | `state.yaml` | Target org/project | | `config.yaml` | CLI settings (color, environment) | ## Check status ```bash theme={null} pc auth status ``` Shows your current authentication method, target organization and project, token expiration (for user login), and environment configuration. # CLI command reference Source: https://docs.pinecone.io/reference/cli/command-reference Complete Pinecone CLI command reference covering syntax, subcommands, flags, help output, and exit codes for auth, index, and project. This document provides a complete reference for all Pinecone CLI commands. ## Command structure The Pinecone CLI uses a hierarchical command structure. Each command consists of a primary command followed by one or more subcommands and optional flags. ```bash theme={null} pc [flags] pc [flags] ``` For example: ```bash theme={null} # Top-level command with flags pc target -o "organization-name" -p "project-name" # Command (index) and subcommand (list) pc index list # Command (index) and subcommand (create) with flags pc index create \ --name my-index \ --dimension 1536 \ --metric cosine \ --cloud aws \ --region us-east-1 # Command (auth) and nested subcommands (local-keys prune) with flags pc auth local-keys prune --id proj-abc123 --skip-confirmation ``` ## Getting help The CLI provides help for commands at every level: ```bash theme={null} # top-level help pc --help pc -h # command help pc auth --help pc index --help pc project --help # subcommmand help pc index create --help pc project create --help pc auth configure --help # nested subcommand help pc auth local-keys prune --help ``` ## Exit codes All commands return exit code `0` for success and `1` for error. ## Available commands This section describes all commands offered by the Pinecone CLI. ### Top-level commands **Description** Authenticate via a web browser. After login, set a [target org and project](/reference/cli/target-context) with `pc target` before accessing data. This command defaults to an initial organization and project to which you have access (these values display in the terminal), but you can change them with `pc target`. **Usage** ```bash theme={null} pc login ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Log in via browser pc login # Then set target context pc target -o "my-org" -p "my-project" ``` This is an alias for `pc auth login`. Both commands perform the same operation. **Description** Clears all authentication data from local storage, including: * User login token * Service account credentials (client ID and secret) * Default (manually specified) API key * Locally managed keys (for all projects) * Target organization and project context **Usage** ```bash theme={null} pc logout ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Clear all credentials and context pc logout ``` This is an alias for `pc auth logout`. Both commands perform the same operation. Does not delete managed API keys from Pinecone's servers. Run `pc auth local-keys prune` before logging out to fully clean up. **Description** Set the target organization and project for the CLI. Supports interactive organization and project selection or direct specification via flags. For details, see [CLI target context](/reference/cli/target-context). **Usage** ```bash theme={null} pc target [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------ | :--------- | :----------------------------- | | `--clear` | | Clear target context | | `--json` | `-j` | Output in JSON format | | `--org` | `-o` | Organization name | | `--organization-id` | | Organization ID | | `--project` | `-p` | Project name | | `--project-id` | | Project ID | | `--show` | `-s` | Display current target context | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Interactive targeting after login pc login pc target # Set specific organization and project pc target -o "my-org" -p "my-project" # Show current context pc target --show # Clear all context pc target --clear ``` **Description** Displays version information for the CLI, including the version number, commit SHA, and build date. **Usage** ```bash theme={null} pc version ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Display version information pc version ``` **Description** Displays information about the currently authenticated user. To use this command, you must be authenticated via user login. **Usage** ```bash theme={null} pc whoami ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc whoami ``` This is an alias for `pc auth whoami`. Both commands perform the same operation. ### Authentication **Description** Selectively clears specific authentication data without affecting other credentials. At least one flag is required. **Usage** ```bash theme={null} pc auth clear [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------ | :--------- | :-------------------------------------------------- | | `--api-key` | | Clear only the default (manually specified) API key | | `--service-account` | | Clear only service account credentials | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Clear only the default (manually specified) API key pc auth clear --api-key pc auth status # Clear service account pc auth clear --service-account ``` More surgical than `pc auth logout`. Does not clear user login token or managed keys. For those, use `pc auth logout` or `pc auth local-keys prune`. **Description** Configures service account credentials or a default (manually specified) API key. Service accounts automatically target the organization and prompt for project selection, unless there is only one project. A default API key overrides any previously specified target organization/project context. When setting a service account, this operation clears the user login token, if one exists. For details, see [CLI target context](/reference/cli/target-context). **Usage** ```bash theme={null} pc auth configure [flags] ``` **Flags** | Long flag | Short flag | Description | | :---------------------- | :--------- | :--------------------------------------------------- | | `--api-key` | | Default API key to use for authentication | | `--client-id` | | Service account client ID | | `--client-secret` | | Service account client secret | | `--client-secret-stdin` | | Read client secret from stdin | | `--json` | `-j` | Output in JSON format | | `--project-id` | `-p` | Target project ID (optional, interactive if omitted) | | `--prompt-if-missing` | | Prompt for missing credentials | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Service account setup (auto-targets org and prompts for project) pc auth configure --client-id my-id --client-secret my-secret # Service account with specific project pc auth configure \ --client-id my-id \ --client-secret my-secret \ -p proj-123 # Default API key (overrides any target context) pc auth configure --api-key pcsk_abc123 ``` `pc auth configure --api-key "YOUR_API_KEY"` does the same thing as `pc config set-api-key "YOUR_API_KEY"`. To learn about targeting a project after authenticating with a service account, see [CLI target context](/reference/cli/target-context). **Description** Displays all [managed API keys](/reference/cli/authentication#managed-keys) stored locally by the CLI, with various details. **Usage** ```bash theme={null} pc auth local-keys list [flags] ``` **Flags** | Long flag | Short flag | Description | | :--------- | :--------- | :----------------------------------------- | | `--json` | `-j` | Output in JSON format | | `--reveal` | | Show the actual API key values (sensitive) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all locally managed keys pc auth local-keys list # Show key values pc auth local-keys list --reveal # After storing a key pc api-key create -n "my-key" --store pc auth local-keys list ``` **Description** Deletes locally stored [managed API keys](/reference/cli/authentication#managed-keys) from local storage and Pinecone's servers. Filters by origin (`cli`/`user`/`all`) or project ID. **Usage** ```bash theme={null} pc auth local-keys prune [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :---------------------------------------------------------- | | `--dry-run` | | Preview deletions without applying | | `--id` | | Prune keys for specific project ID only | | `--json` | `-j` | Output in JSON format | | `--origin` | `-o` | Filter by origin - `cli`, `user`, or `all` (default: `all`) | | `--skip-confirmation` | | Skip confirmation prompt | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Preview deletions pc auth local-keys prune --dry-run # Delete CLI-created keys only pc auth local-keys prune -o cli --skip-confirmation # Delete for specific project pc auth local-keys prune --id proj-abc123 # Before/after check pc auth local-keys list pc auth local-keys prune -o cli pc auth local-keys list ``` This deletes keys from both local storage and Pinecone servers. Use `--dry-run` to preview before committing. **Description** Authenticate via user login in the web browser. After login, [set a target org and project](/reference/cli/target-context). **Usage** ```bash theme={null} pc auth login pc login # shorthand ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Login and set target pc auth login pc target -o "my-org" -p "my-project" pc index list ``` Tokens refresh automatically and remain valid for up to 120 days. If you're inactive for more than 30 days, you must re-authenticate. Logging in clears any existing service account credentials. This command does the same thing as `pc login`. **Description** Clears all authentication data from local storage, including: * User login token * Service account credentials (client ID and secret) * Default (manually specified) API key * Locally managed keys (for all projects) * Target organization and project context **Usage** ```bash theme={null} pc auth logout ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Clear all credentials and context pc auth logout ``` This command does the same thing as `pc logout`. Does not delete managed API keys from Pinecone's servers. Run `pc auth local-keys prune` before logging out to fully clean up. **Description** Shows details about all configured authentication methods. **Usage** ```bash theme={null} pc auth status [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Check status after login pc auth login pc auth status # JSON output for scripting pc auth status --json ``` **Description** Displays information about the currently authenticated user. To use this command, you must be authenticated via user login. **Usage** ```bash theme={null} pc auth whoami ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc auth whoami ``` This command does the same thing as `pc whoami`. ### Indexes **Description** Modifies the configuration of an existing index. **Usage** ```bash theme={null} pc index configure [flags] ``` **Flags** | Long flag | Short flag | Description | | :----------------------- | :--------- | :-------------------------------------------------------------- | | `--index-name` | `-i` | Name of index to configure (required) | | `--deletion-protection` | | Enable or disable deletion protection - `enabled` or `disabled` | | `--tags` | | Custom user tags (key=value pairs) | | `--json` | `-j` | Output in JSON format | | **Dedicated read nodes** | | | | `--read-mode` | | Read capacity mode - `ondemand` or `dedicated` | | `--read-node-type` | | Node type for dedicated read - `b1` or `t1` | | `--read-shards` | | Number of shards for dedicated read capacity | | `--read-replicas` | | Number of replicas for dedicated read capacity | | **Integrated embedding** | | | | `--model` | | Embedding model name | | `--field-map` | | Field mapping for embedding (key=value pairs) | | `--read-parameters` | | Read parameters for embedding model (key=value pairs) | | `--write-parameters` | | Write parameters for embedding model (key=value pairs) | | **Pods** | | | | `--pod-type` | `-t` | Type of pod to use; can only upgrade when configuring | | `--replicas` | `-r` | Number of replicas of the index to configure | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Enable deletion protection pc index configure --index-name my-index --deletion-protection enabled # Add tags pc index configure --index-name my-index --tags environment=production,team=ml # Switch to dedicated read capacity pc index configure --index-name my-index \ --read-mode dedicated \ --read-node-type b1 \ --read-shards 2 \ --read-replicas 2 # Verify changes pc index describe --index-name my-index ``` Configuration changes may take some time to take effect. **Description** Creates a new index in your Pinecone project. Supports serverless, pod-based, integrated (with embedding model), and BYOC (Bring Your Own Cloud) index types. **Usage** ```bash theme={null} pc index create [flags] ``` **Flags** | Long flag | Short flag | Description | | :----------------------- | :--------- | :----------------------------------------------------------------------------- | | `--name` | `-n` | Index name (required) | | `--dimension` | `-d` | Vector dimension (required for standard indexes, optional for integrated) | | `--metric` | `-m` | Similarity metric - `cosine`, `euclidean`, or `dotproduct` (default: `cosine`) | | `--cloud` | `-c` | Cloud provider - `aws`, `gcp`, or `azure` | | `--region` | `-r` | Cloud region | | `--vector-type` | `-v` | Vector type - `dense` or `sparse` (serverless only) | | `--source-collection` | | Name of the source collection from which to create the index | | `--schema` | | Metadata schema to control which fields are indexed (comma-separated) | | `--deletion-protection` | | Deletion protection - `enabled` or `disabled` | | `--tags` | | Custom user tags (key=value pairs) | | `--json` | `-j` | Output in JSON format | | **Integrated indexes** | | | | `--model` | | Integrated embedding model name | | `--field-map` | | Field mapping for integrated embedding (key=value pairs) | | `--read-parameters` | | Read parameters for embedding model (key=value pairs) | | `--write-parameters` | | Write parameters for embedding model (key=value pairs) | | **BYOC indexes** | | | | `--byoc-environment` | | BYOC environment to use for the index | | **Dedicated read nodes** | | | | `--read-mode` | | Read capacity mode - `ondemand` or `dedicated` (default: `ondemand`) | | `--read-node-type` | | Node type for dedicated read - `b1` or `t1` | | `--read-shards` | | Number of shards (each shard provides 250 GB storage) | | `--read-replicas` | | Number of replicas for higher throughput | | **Pod-based indexes** | | | | `--environment` | | Environment of the index to create (for example, `us-east-1-aws`) | | `--pod-type` | | Type of pod to use (for example, `p1.x1`, `s1.x2`) | | `--shards` | | Number of shards (default: `1`) | | `--replicas` | | Number of replicas (default: `1`) | | `--metadata-config` | | Comma-separated list of metadata fields to index for search | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Create serverless index pc index create -n my-index -d 1536 -m cosine -c aws -r us-east-1 # Create sparse vector index pc index create -n sparse-index -m dotproduct -c aws -r us-east-1 --vector-type sparse # With integrated embedding model pc index create \ -n my-index \ -m cosine \ -c aws \ -r us-east-1 \ --model multilingual-e5-large \ --field-map text=chunk_text # With dedicated read capacity pc index create \ -n my-index \ -d 1536 \ -m cosine \ -c aws \ -r us-east-1 \ --read-mode dedicated \ --read-node-type b1 \ --read-shards 2 \ --read-replicas 2 # With deletion protection pc index create \ -n my-index \ -d 1536 \ -m cosine \ -c aws \ -r us-west-2 \ --deletion-protection enabled # From collection pc index create \ -n my-index \ -d 1536 \ -m cosine \ -c aws \ -r eu-west-1 \ --source-collection my-collection # Create pod-based index pc index create \ -n my-index \ -d 1536 \ -m cosine \ --environment us-east-1-aws \ --pod-type p1.x1 \ --shards 1 \ --replicas 1 ``` For a list of valid regions for a serverless index, see [Create a serverless index](/guides/index-data/create-an-index). **Description** Permanently deletes an index and all its data. This operation cannot be undone. **Usage** ```bash theme={null} pc index delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :--------------------------------------------------------- | | `--index-name` | `-i` | Name of index to delete (required) | | `--skip-confirmation` | | Skip the deletion confirmation prompt | | `--json` | `-j` | Output in JSON format (also skips the confirmation prompt) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete an index (prompts for confirmation) pc index delete --index-name my-index # Skip the confirmation prompt pc index delete --index-name my-index --skip-confirmation # List before and after pc index list pc index delete --index-name test-index --skip-confirmation pc index list ``` This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. **Description** Displays detailed configuration and status information for a specific index. **Usage** ```bash theme={null} pc index describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :-------------------- | | `--index-name` | `-i` | Index name (required) | | `--json` | `-j` | Output in JSON format | The `--name`/`-n` flag is a deprecated alias for `--index-name`/`-i`. **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe an index pc index describe -i my-index # JSON output pc index describe -i my-index -j # Check newly created index pc index create -n test-index -d 1536 -m cosine -c aws -r us-east-1 pc index describe -i test-index ``` **Description** Displays statistics for an index, including total vector count and namespace breakdown. Optionally filter results with a metadata filter. **Usage** ```bash theme={null} pc index stats [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--filter` | `-f` | Metadata filter (inline JSON, `./path.json`, or `-` for stdin) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Get stats for an index pc index stats -i my-index # Get stats with a metadata filter pc index stats -i my-index --filter '{"genre":{"$eq":"rock"}}' # Filter from file pc index stats -i my-index --filter ./filter.json # JSON output pc index stats -i my-index -j ``` **Description** Displays all indexes in your current target project, including various details. **Usage** ```bash theme={null} pc index list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------------------------------------- | | `--json` | `-j` | Output in JSON format (includes full index details) | | `--wide` | `-w` | Show additional columns (host, embed, tags) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all indexes pc index list # Show additional details pc index list --wide # JSON output for scripting pc index list -j # After creating indexes pc index create -n test-1 -d 768 -m cosine -c aws -r us-east-1 pc index list ``` ### Namespaces **Description** Creates a new namespace within an index. Namespaces allow you to partition vectors within an index. **Usage** ```bash theme={null} pc index namespace create [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :-------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--name` | | Namespace name (required) | | `--schema` | | Metadata schema for the namespace (comma-separated) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Create a namespace pc index namespace create -i my-index --name tenant-a # Create with metadata schema (comma-separated list of filterable metadata fields) pc index namespace create -i my-index --name tenant-b --schema "category,brand" # JSON output pc index namespace create -i my-index --name tenant-c -j ``` **Description** Deletes a namespace and all its vectors from an index. This operation cannot be undone. **Usage** ```bash theme={null} pc index namespace delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :--------------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--name` | | Namespace name (required); use `__default__` for the default namespace | | `--skip-confirmation` | | Skip the deletion confirmation prompt | | `--json` | `-j` | Output in JSON format (also skips the confirmation prompt) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete a namespace (prompts for confirmation) pc index namespace delete -i my-index --name tenant-a # Delete the default namespace pc index namespace delete -i my-index --name __default__ # Skip the confirmation prompt pc index namespace delete -i my-index --name tenant-a --skip-confirmation ``` Deleting a namespace removes all vectors in that namespace. This operation cannot be undone. **Description** Displays detailed information about a specific namespace, including record count and schema configuration. **Usage** ```bash theme={null} pc index namespace describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :--------------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--name` | | Namespace name (required); use `__default__` for the default namespace | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe a namespace pc index namespace describe -i my-index --name tenant-a # Describe the default namespace pc index namespace describe -i my-index --name __default__ # JSON output pc index namespace describe -i my-index --name tenant-a -j ``` **Description** Lists all namespaces within an index, including vector counts. **Usage** ```bash theme={null} pc index namespace list [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :----------------------------- | | `--index-name` | `-i` | Index name (required) | | `--limit` | `-l` | Maximum number of results | | `--pagination-token` | `-p` | Pagination token for next page | | `--prefix` | | Filter namespaces by prefix | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all namespaces pc index namespace list -i my-index # Filter by prefix pc index namespace list -i my-index --prefix "tenant-" # Limit results pc index namespace list -i my-index --limit 10 # JSON output pc index namespace list -i my-index -j ``` ### Vectors **Description** Deletes vectors from an index by ID, filter, or deletes all vectors in a namespace. **Usage** ```bash theme={null} pc index vector delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :------------------------------------------------------------------------ | | `--index-name` | `-i` | Index name (required) | | `--namespace` | | Namespace to delete from (default: `__default__`) | | `--ids` | | Vector IDs to delete (inline JSON array, `./path.json`, or `-` for stdin) | | `--filter` | | Metadata filter (inline JSON, `./path.json`, or `-` for stdin) | | `--all-vectors` | | Delete all vectors in the namespace | | `--skip-confirmation` | | Skip the confirmation prompt shown for `--all-vectors` | | `--json` | `-j` | Output in JSON format (also skips the confirmation prompt) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete specific vectors pc index vector delete -i my-index --ids '["id1"]' # Delete multiple vectors (inline JSON array, or JSON array in a file) pc index vector delete -i my-index --ids '["id1", "id2"]' # Delete by filter pc index vector delete -i my-index --filter '{"genre":"classical"}' # Delete all vectors in a namespace (prompts for confirmation) pc index vector delete -i my-index --namespace old-data --all-vectors # Delete all vectors without the prompt pc index vector delete -i my-index --namespace old-data --all-vectors --skip-confirmation ``` Only `--all-vectors` prompts for confirmation. Targeted deletes with `--ids` or `--filter` proceed without a prompt. Pass `--skip-confirmation` (or `--json`) to bypass the `--all-vectors` prompt. Vector deletion is permanent and cannot be undone. **Description** Retrieves vectors by their IDs or by a metadata filter, returning the vector values and metadata. **Usage** ```bash theme={null} pc index vector fetch [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :----------------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--namespace` | | Namespace to fetch from (default: `__default__`) | | `--ids` | | Vector IDs to fetch (inline JSON array, `./path.json`, or `-` for stdin) | | `--filter` | `-f` | Metadata filter (inline JSON, `./path.json`, or `-` for stdin) | | `--limit` | `-l` | Maximum number of vectors to fetch | | `--pagination-token` | `-p` | Pagination token for next page | | `--body` | | Request body JSON (inline, `./path.json`, or `-` for stdin) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Fetch specific vectors by ID pc index vector fetch -i my-index --ids '["123","456","789"]' # Fetch from a file pc index vector fetch -i my-index --ids ./ids.json # Fetch by metadata filter pc index vector fetch -i my-index --filter '{"genre":{"$eq":"rock"}}' # Fetch from a namespace pc index vector fetch -i my-index --namespace tenant-a --ids '["doc-123"]' # JSON output pc index vector fetch -i my-index --ids '["vec1"]' -j ``` Use either `--ids` or `--filter`, not both. When using `--ids`, pagination flags are not applicable. **Description** Lists vector IDs in a namespace with optional pagination. **Usage** ```bash theme={null} pc index vector list [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :---------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--namespace` | | Namespace to list from (default: `__default__`) | | `--limit` | `-l` | Maximum number of IDs to return | | `--pagination-token` | `-p` | Pagination token for next page | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List vector IDs pc index vector list -i my-index # List from a namespace with limit pc index vector list -i my-index --namespace tenant-a --limit 50 # JSON output pc index vector list -i my-index -j ``` **Description** Queries an index for similar vectors using dense vectors, sparse vectors, or vector ID. **Usage** ```bash theme={null} pc index vector query [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :-------------------------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--namespace` | | Namespace to query (default: `__default__`) | | `--id` | | Query by vector ID | | `--vector` | `-v` | Query vector values (inline JSON array, `./path.json`, or `-` for stdin) | | `--sparse-indices` | | Sparse vector indices (inline JSON uint32 array, `./path.json`, or `-` for stdin) | | `--sparse-values` | | Sparse vector values (inline JSON array, `./path.json`, or `-` for stdin) | | `--top-k` | `-k` | Number of results to return (default: 10) | | `--filter` | `-f` | Metadata filter (inline JSON, `./path.json`, or `-` for stdin) | | `--include-values` | | Include vector values in results | | `--include-metadata` | | Include metadata in results | | `--body` | | Request body JSON (inline, `./path.json`, or `-` for stdin) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Query by vector ID pc index vector query -i my-index --id "doc-123" -k 10 --include-metadata # Query by vector values pc index vector query -i my-index --vector '[0.1, 0.2, 0.3]' -k 25 # Query with metadata filter pc index vector query -i my-index \ --vector '[0.1, 0.2, 0.3]' \ --filter '{"genre":{"$eq":"sci-fi"}}' \ --include-metadata # Query from file (file contains a JSON array that specifies the query vector) pc index vector query -i my-index --vector ./embedding.json -k 20 # Query with sparse vectors (inline) pc index vector query -i my-index \ --sparse-indices '[0, 5, 12]' \ --sparse-values '[0.5, 0.3, 0.8]' \ -k 15 # Query with sparse vectors from files # indices.json: [0, 5, 12] # values.json: [0.5, 0.3, 0.8] pc index vector query -i my-index \ --sparse-indices ./indices.json \ --sparse-values ./values.json \ -k 15 # Query from stdin (extract embedding from a document) # doc.json: {"id": "doc-123", "embedding": [0.1, 0.2, 0.3], "text": "..."} jq -c '.embedding' doc.json | pc index vector query -i my-index --vector - -k 10 ``` Use `--id`, `--vector`, or sparse vectors (`--sparse-indices` and `--sparse-values`) to specify what to query against. These options are mutually exclusive. **Description** Updates a vector's values, sparse values, or metadata by ID, or updates metadata for multiple vectors matching a filter. **Usage** ```bash theme={null} pc index vector update [flags] ``` **Flags** | Long flag | Short flag | Description | | :----------------- | :--------- | :----------------------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--namespace` | | Namespace containing the vector (default: `__default__`) | | `--id` | | Vector ID to update | | `--values` | | New vector values (inline JSON array, `./path.json`, or `-` for stdin) | | `--sparse-indices` | | New sparse indices (inline JSON uint32 array, `./path.json`, or `-` for stdin) | | `--sparse-values` | | New sparse values (inline JSON array, `./path.json`, or `-` for stdin) | | `--metadata` | | New or updated metadata (inline JSON, `./path.json`, or `-` for stdin) | | `--filter` | | Metadata filter for bulk update (inline JSON, `./path.json`, or `-` for stdin) | | `--dry-run` | | Preview how many records would be updated without applying changes | | `--body` | | Request body JSON (inline, `./path.json`, or `-` for stdin) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Update metadata for a single vector pc index vector update -i my-index --id "vec1" --metadata '{"category":"updated"}' # Update values for a single vector pc index vector update -i my-index --id "vec1" --values '[0.2, 0.3, 0.4]' # Update sparse values # indices.json: [0, 5, 12] # values.json: [0.5, 0.3, 0.8] pc index vector update -i my-index --id "vec1" \ --sparse-indices ./indices.json \ --sparse-values ./values.json # Bulk update metadata by filter (preview first) pc index vector update -i my-index \ --filter '{"genre":{"$eq":"sci-fi"}}' \ --metadata '{"genre":"fantasy"}' \ --dry-run # Apply the bulk update pc index vector update -i my-index \ --filter '{"genre":{"$eq":"sci-fi"}}' \ --metadata '{"genre":"fantasy"}' ``` Use either `--id` for single vector updates or `--filter` for bulk updates. These options are mutually exclusive. **Description** Inserts or updates vectors in an index from a JSON or JSONL file, or inline JSON. The CLI automatically batches vectors for efficient uploading. Files can contain any number of vectors—the CLI splits them into batches and sends multiple API requests as needed. **Usage** ```bash theme={null} pc index vector upsert [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :--------------------------------------------------------------------------------- | | `--index-name` | `-i` | Index name (required) | | `--namespace` | | Namespace to upsert into (default: `__default__`) | | `--body` | | Request body JSON or JSONL (inline, `./path.json[l]`, or `-` for stdin) (required) | | `--batch-size` | `-b` | Size of batches to upsert (default: 500) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Upsert from JSON file (with "vectors" array) # vectors.json: {"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]} pc index vector upsert -i my-index --body ./vectors.json # Upsert with inline JSON pc index vector upsert -i my-index --body '{"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]}' # Upsert from JSONL file (one vector per line) # vectors.jsonl: {"id": "vec1", "values": [0.1, 0.2, 0.3]} # {"id": "vec2", "values": [0.4, 0.5, 0.6]} pc index vector upsert -i my-index --body ./vectors.jsonl # Upsert from stdin (same format as JSON or JSONL file) cat vectors.json | pc index vector upsert -i my-index --body - # Custom batch size (default: 500, max: 1000 per API request) pc index vector upsert -i my-index --body ./vectors.json --batch-size 1000 ``` **Batch size limits:** The API accepts up to 1000 vectors per request. The CLI defaults to batches of 500 vectors, but you can adjust this with `--batch-size` (up to 1000). Large files are automatically split into multiple batches. **File size:** There's no explicit file size limit—the CLI reads the entire file into memory and batches it automatically. Very large files are supported as long as they fit in available system memory. ### Records **Description** Search an index namespace with a query text, query vector, or record ID and return the most similar records, along with their similarity scores. Optionally, rerank the initial results based on their relevance to the query. Searching with text is supported only for indexes with an integrated embedding configured. Searching with a query vector or record ID is supported for all indexes. Exactly one primary query mode must be provided: * `--inputs` — query text (requires an index with integrated embedding) * `--id` — use an existing record's vector as the query * `--vector` — provide a dense vector directly (all index types) * `--sparse-indices` + `--sparse-values` — sparse vector (all index types) Combine `--vector` with `--sparse-indices`/`--sparse-values` for hybrid search. Use `--body` to pass a full request object; flags take precedence over `--body` when both specify the same field. **Usage** ```bash theme={null} pc index record search [flags] ``` **Flags** | Long flag | Short flag | Description | | :----------------- | :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--index-name` | `-i` | Name of the index to search (required) | | `--inputs` | | Query inputs for text search (inline JSON, `./path.json`, or `-` for stdin); requires integrated embedding. Mutually exclusive with `--id` and `--vector`. | | `--id` | | Use an existing record's vector by ID for the query. Mutually exclusive with `--inputs` and `--vector`. | | `--vector` | `-v` | Dense vector values to search against (inline JSON float32 array, `./path.json`, or `-` for stdin). Mutually exclusive with `--inputs` and `--id`. | | `--sparse-indices` | | Sparse vector indices (inline JSON int32 array, `./path.json`, or `-` for stdin). Must be used together with `--sparse-values`. | | `--sparse-values` | | Sparse vector values (inline JSON float32 array, `./path.json`, or `-` for stdin). Must be used together with `--sparse-indices`. | | `--top-k` | `-k` | Number of results to return (required) | | `--namespace` | | Namespace to search | | `--filter` | | Metadata filter (inline JSON, `./path.json`, or `-` for stdin) | | `--rerank` | | Re-score results using an inference model (inline JSON, `./path.json`, or `-` for stdin). Required fields: `model` (string), `rank_fields` (string array). | | `--match-terms` | | Keyword terms filter for sparse integrated indexes (inline JSON, `./path.json`, or `-` for stdin). Required field: `terms` (string array). Requires `--inputs`. | | `--fields` | | Fields to return in results (inline JSON string array, `./path.json`, or `-` for stdin) | | `--body` | | Full request body JSON (inline, `./path.json`, or `-` for stdin). Flags take precedence when both specify the same field. | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Examples** ```bash theme={null} # Text search (integrated embedding indexes only) pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --top-k 10 pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --namespace my-namespace --top-k 5 pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --filter '{"category":"health"}' --top-k 10 pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --fields '["_id","chunk_text","category"]' --top-k 10 pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --rerank '{"model":"bge-reranker-v2-m3","rank_fields":["chunk_text"]}' --top-k 10 pc index record search --index-name my-index --inputs '{"text":"disease prevention"}' --match-terms '{"terms":["vaccine","prevention"]}' --top-k 10 # Search by record ID for query vector (all index types) pc index record search --index-name my-index --id rec-123 --top-k 10 # Vector search (all index types) pc index record search --index-name my-index --vector '[0.1,0.2,0.3]' --top-k 10 pc index record search --index-name my-index --sparse-indices '[1,5,9]' --sparse-values '[0.4,0.8,0.2]' --top-k 10 pc index record search --index-name my-index --vector '[0.1,0.2,0.3]' --sparse-indices '[1,5,9]' --sparse-values '[0.4,0.8,0.2]' --top-k 10 # Full request body (must include top_k in the body) pc index record search --index-name my-index --body ./search.json ``` ```text CLI theme={null} Usage: 5 (read units) ID SCORE FIELDS rec-001 0.912340 {"category":"health","chunk_text":"vaccine research..."} rec-002 0.887210 {"category":"health","chunk_text":"disease prevention..."} ``` **Description** Upsert records into an integrated index namespace from a JSON or JSONL payload. The `--body` flag accepts a JSON object containing a `"records"` array of `IntegratedRecord` objects, a raw JSON array of records, or a JSONL stream of records (one object per line). The value can be inline JSON, a path to a `.json` or `.jsonl` file, or `-` to read from stdin. Records are sent in batches. The default batch size is 96 (the API maximum). Use `--batch-size` to send smaller batches. **Usage** ```bash theme={null} pc index record upsert [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :-------------------------------------------------------------------------------------- | | `--index-name` | `-i` | Name of the index to upsert into (required) | | `--body` | | Request body JSON or JSONL (inline JSON, `./path.json[l]`, or `-` for stdin) (required) | | `--namespace` | | Namespace to upsert into | | `--batch-size` | `-b` | Number of records per batch (default: `96`, max: `96`) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Examples** ```bash theme={null} # Upsert from a JSON file pc index record upsert --index-name my-index --body ./records.json # Upsert from a JSONL file into a specific namespace pc index record upsert --index-name my-index --namespace my-namespace --body ./records.jsonl # Upsert from stdin cat records.jsonl | pc index record upsert --index-name my-index --namespace my-namespace --body - ``` ### Collections **Description** Creates a static copy of a pod-based index as a collection. Collections can be used to store a snapshot of an index's data for backup or migration purposes. **Usage** ```bash theme={null} pc index collection create [flags] ``` **Flags** | Long flag | Short flag | Description | | :--------- | :--------- | :---------------------------------------------------------- | | `--name` | `-n` | Name to give the collection (required) | | `--source` | `-s` | Name of the pod-based index to use as the source (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Create a collection from a pod-based index pc index collection create --name my-collection --source my-index ``` ```text CLI theme={null} ATTRIBUTE VALUE Name my-collection State Initializing Dimension 1536 Size 0 VectorCount 0 Environment us-east-1-aws ``` **Description** Deletes a collection permanently. This action cannot be undone. **Usage** ```bash theme={null} pc index collection delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :--------------------------------------------------------- | | `--name` | `-n` | Name of the collection to delete (required) | | `--skip-confirmation` | | Skip the deletion confirmation prompt | | `--json` | `-j` | Output in JSON format (also skips the confirmation prompt) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete a collection (prompts for confirmation) pc index collection delete --name my-collection # Skip the confirmation prompt pc index collection delete --name my-collection --skip-confirmation ``` This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. **Description** Returns detailed information about a single collection, including its state, dimension, size, vector count, and environment. **Usage** ```bash theme={null} pc index collection describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------------------------------- | | `--name` | `-n` | Name of the collection to describe (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe a collection pc index collection describe --name my-collection ``` ```text CLI theme={null} ATTRIBUTE VALUE Name my-collection State Ready Dimension 1536 Size 104857600 VectorCount 10000 Environment us-east-1-aws ``` **Description** Lists all collections in your current project, sorted alphabetically by name. **Usage** ```bash theme={null} pc index collection list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all collections pc index collection list ``` ```text CLI theme={null} NAME DIMENSION SIZE STATUS VECTORS ENVIRONMENT my-collection 1536 104857600 Ready 10000 us-east-1-aws ``` ### Backups **Description** Creates a backup of a serverless index. Backups are static copies that only consume storage. **Usage** ```bash theme={null} pc index backup create [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------- | :--------- | :------------------------------------------------------------------- | | `--index-name` | `-i` | Name of the index to back up (required) | | `--name` | | Human-readable label for the backup (the backup ID is always a UUID) | | `--description` | `-d` | Description for the backup | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Create a backup pc index backup create -i my-index # Create with name and description pc index backup create -i my-index --name "nightly-backup" -d "Nightly backup before deployment" # JSON output pc index backup create -i my-index -j ``` **Description** Permanently deletes a backup. This operation cannot be undone. **Usage** ```bash theme={null} pc index backup delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :--------------------------------------------------------- | | `--id` | `-i` | Backup ID to delete (required) | | `--skip-confirmation` | | Skip the deletion confirmation prompt | | `--json` | `-j` | Output in JSON format (also skips the confirmation prompt) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete a backup by ID (prompts for confirmation) pc index backup delete -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f # Skip the confirmation prompt pc index backup delete -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f --skip-confirmation ``` This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. Backup deletion is permanent and cannot be undone. **Description** Displays detailed information about a specific backup. **Usage** ```bash theme={null} pc index backup describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :------------------------------- | | `--id` | `-i` | Backup ID to describe (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe a backup pc index backup describe -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f # JSON output pc index backup describe -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -j ``` **Description** Lists backups in the current project, optionally filtered by index name. **Usage** ```bash theme={null} pc index backup list [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :----------------------------- | | `--index-name` | `-i` | Filter backups by index name | | `--limit` | `-l` | Maximum number of results | | `--pagination-token` | `-p` | Pagination token for next page | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all backups in the project pc index backup list # List backups for a specific index pc index backup list --index-name my-index # Limit results pc index backup list --limit 10 # JSON output pc index backup list -j ``` **Description** Creates a new index from a backup. **Usage** ```bash theme={null} pc index restore [flags] ``` **Flags** | Long flag | Short flag | Description | | :---------------------- | :--------- | :--------------------------------------------------- | | `--id` | `-i` | Backup ID (UUID) to restore from (required) | | `--name` | `-n` | Name for the new index (required) | | `--deletion-protection` | | Enable deletion protection - `enabled` or `disabled` | | `--tags` | `-t` | Tags to apply to the new index (key=value pairs) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Restore an index from a backup pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index # Restore with tags and deletion protection pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index \ --tags env=prod,team=search \ --deletion-protection enabled # JSON output pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index -j ``` **Description** Displays the status and details of a restore job. **Usage** ```bash theme={null} pc index restore describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :------------------------------------ | | `--id` | `-i` | Restore job ID to describe (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe a restore job pc index restore describe -i rj-abc123 # JSON output pc index restore describe -i rj-abc123 -j ``` **Description** Lists all restore jobs in the current project. **Usage** ```bash theme={null} pc index restore list [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :----------------------------- | | `--limit` | `-l` | Maximum number of results | | `--pagination-token` | `-p` | Pagination token for next page | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List restore jobs pc index restore list # Limit results pc index restore list --limit 10 # JSON output pc index restore list -j ``` ### Imports **Description** Start an import that loads vector data from a storage provider into a serverless index. The URI must begin with the scheme of a supported provider (for example, `s3://`). For private buckets, configure a storage integration in the Pinecone console and pass the integration ID with `--integration-id`. Use `--error-mode` to control behavior when records fail: `continue` skips failing records and keeps going; `abort` stops the import on first error. Defaults to `continue`. **Usage** ```bash theme={null} pc index import start [flags] ``` **Flags** | Long flag | Short flag | Description | | :----------------- | :--------- | :-------------------------------------------------------------------- | | `--index-name` | `-i` | Name of the index to import into (required) | | `--uri` | `-u` | URI of the data to import, for example `s3://bucket/path/` (required) | | `--integration-id` | | Storage integration ID for private buckets | | `--error-mode` | | How to handle record errors: `continue` (default) or `abort` | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Examples** ```bash theme={null} # Start an import from a public S3 bucket pc index import start --index-name my-index --uri s3://my-bucket/data/ # Start an import from a private bucket using a storage integration pc index import start --index-name my-index --uri s3://my-bucket/data/ --integration-id intg-123 # Abort on the first error instead of continuing pc index import start --index-name my-index --uri s3://my-bucket/data/ --error-mode abort # JSON output pc index import start --index-name my-index --uri s3://my-bucket/data/ -j ``` ```text CLI theme={null} Import imp-abc123 started. ATTRIBUTE VALUE Import ID imp-abc123 ``` **Description** Show the current status and details of an import operation, including percent complete, records imported, and any error messages. **Usage** ```bash theme={null} pc index import describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :------------------------------------------------- | | `--index-name` | `-i` | Name of the index the import belongs to (required) | | `--id` | | ID of the import to describe (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe an import operation pc index import describe --index-name my-index --id import-123 # JSON output pc index import describe --index-name my-index --id import-123 -j ``` ```text CLI theme={null} ATTRIBUTE VALUE Import ID import-123 Status InProgress URI s3://my-bucket/data/ Percent Complete 45.0% Records Imported 450 Created At 2024-01-15 12:00:00 Finished At - Error None ``` **Description** List bulk import operations for the given index, with optional pagination. **Usage** ```bash theme={null} pc index import list [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :-------------------------------------------------------- | | `--index-name` | `-i` | Name of the index to list imports for (required) | | `--limit` | `-l` | Maximum number of imports to return | | `--pagination-token` | `-p` | Pagination token to continue a previous listing operation | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Examples** ```bash theme={null} # List all imports for an index pc index import list --index-name my-index # List imports with a page size limit pc index import list --index-name my-index --limit 10 # Continue paginating from a previous call pc index import list --index-name my-index --pagination-token eyJ... # JSON output pc index import list --index-name my-index -j ``` ```text CLI theme={null} IMPORT ID STATUS URI PERCENT RECORDS CREATED FINISHED imp-abc123 Completed s3://my-bucket/data/ 100.0% 1000 2024-01-15 12:00:00 2024-01-15 12:05:00 imp-def456 InProgress s3://other-bucket/data/ 45.0% 450 2024-01-15 13:00:00 - ``` **Description** Cancel an import operation that is currently pending or in progress. Already-completed or failed imports cannot be canceled. **Usage** ```bash theme={null} pc index import cancel [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------- | :--------- | :------------------------------------------------- | | `--index-name` | `-i` | Name of the index the import belongs to (required) | | `--id` | | ID of the import to cancel (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Cancel an import operation pc index import cancel --index-name my-index --id import-123 # JSON output pc index import cancel --index-name my-index --id import-123 -j ``` ```text CLI theme={null} Import import-123 canceled. ``` ### Projects **Description** Creates a new project in your [target organization](/reference/cli/target-context), using the specified configuration. **Usage** ```bash theme={null} pc project create [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :------------------------------------------------------------- | | `--force-encryption` | | Enable encryption with CMEK | | `--json` | `-j` | Output in JSON format | | `--name` | `-n` | Project name (required) | | `--target` | | Automatically target the project in the CLI after it's created | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Basic project creation pc project create -n "demo-project" ``` **Description** Permanently deletes a project and all its resources. This operation cannot be undone. **Usage** ```bash theme={null} pc project delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :---------------------------------------------------------- | | `--id` | `-i` | Project ID (optional, uses target project if not specified) | | `--json` | `-j` | Output in JSON format | | `--skip-confirmation` | | Skip confirmation prompt | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete target project pc project delete # Delete specific project pc project delete -i proj-abc123 # Skip confirmation pc project delete -i proj-abc123 --skip-confirmation ``` Must delete all indexes and collections in the project first. If the deleted project is your current target, set a new target after deleting it. **Description** Displays detailed information about a specific project, including various details. **Usage** ```bash theme={null} pc project describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--id` | `-i` | Project ID (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe a project pc project describe -i proj-abc123 # JSON output pc project describe -i proj-abc123 --json # Find ID and describe pc project list pc project describe -i proj-abc123 ``` **Description** Displays all projects in your [target organization](/reference/cli/target-context), including various details. **Usage** ```bash theme={null} pc project list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all projects pc project list # JSON output pc project list --json # List after login pc auth login pc auth target -o "my-org" pc project list ``` **Description** Modifies the configuration of the [target project](/reference/cli/target-context), or a specific project ID. **Usage** ```bash theme={null} pc project update [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :---------------------------------- | | `--force-encryption` | `-f` | Enable/disable encryption with CMEK | | `--id` | `-i` | Project ID (required) | | `--json` | `-j` | Output in JSON format | | `--name` | `-n` | New project name | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Update name pc project update -i proj-abc123 -n "new-name" ``` ### Organizations **Description** Permanently deletes an organization and all its resources. This operation cannot be undone. **Usage** ```bash theme={null} pc organization delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :------------------------- | | `--id` | `-i` | Organization ID (required) | | `--json` | `-j` | Output in JSON format | | `--skip-confirmation` | | Skip confirmation prompt | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete an organization pc organization delete -i org-abc123 # Skip confirmation pc organization delete -i org-abc123 --skip-confirmation ``` This is a highly destructive action. Deletion is permanent. If the deleted organization is your current [target](/reference/cli/target-context), set a new target after deleting. **Description** Displays detailed information about a specific organization, including name, ID, creation date, payment status, plan, and support tier. **Usage** ```bash theme={null} pc organization describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :------------------------- | | `--id` | `-i` | Organization ID (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe an organization pc organization describe -i org-abc123 # JSON output pc organization describe -i org-abc123 --json # Find ID and describe pc organization list pc organization describe -i org-abc123 ``` **Description** Displays all organizations that the authenticated user has access to, including name, ID, creation date, payment status, plan, and support tier. **Usage** ```bash theme={null} pc organization list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List all organizations pc organization list # JSON output pc organization list --json # List after login pc auth login pc organization list ``` **Description** Modifies the configuration of the [target organization](/reference/cli/target-context), or a specific organization ID. **Usage** ```bash theme={null} pc organization update [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :------------------------- | | `--id` | `-i` | Organization ID (required) | | `--json` | `-j` | Output in JSON format | | `--name` | `-n` | New organization name | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Update name pc organization update -i org-abc123 -n "new-name" # Verify changes pc organization update -i org-abc123 -n "Acme Corp" pc organization describe -i org-abc123 ``` ### API keys **Description** Creates a new API key for the current [target project](/reference/cli/target-context) or a specific project ID. Optionally stores the key locally for CLI use. **Usage** ```bash theme={null} pc api-key create [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------------------------------------------------------------------------- | | `--id` | `-i` | Project ID (optional, uses target project if not specified) | | `--json` | `-j` | Output in JSON format | | `--name` | `-n` | Key name (required) | | `--roles` | | Roles to assign (default: `ProjectEditor`) | | `--store` | | Store the key locally for CLI use (automatically replaces any existing CLI-managed key) | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Basic key creation pc api-key create -n "my-key" # Create and store locally pc api-key create -n "my-key" --store # Create with specific role pc api-key create -n "my-key" --store --roles ProjectEditor # Create for specific project pc api-key create -n "my-key" -i proj-abc123 ``` API keys are scoped to a specific organization and project. **Description** Permanently deletes an API key. Applications using this key immediately lose access. **Usage** ```bash theme={null} pc api-key delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :----------------------- | | `--id` | `-i` | API key ID (required) | | `--skip-confirmation` | | Skip confirmation prompt | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Delete an API key pc api-key delete -i key-abc123 # Skip confirmation pc api-key delete -i key-abc123 --skip-confirmation # Delete and clean up local storage pc api-key delete -i key-abc123 pc auth local-keys prune --skip-confirmation ``` Deletion is permanent. Applications using this key immediately lose access to Pinecone. **Description** Displays detailed information about a specific API key, including its name, ID, project ID, and roles. **Usage** ```bash theme={null} pc api-key describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--id` | `-i` | API key ID (required) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Describe an API key pc api-key describe -i key-abc123 # JSON output pc api-key describe -i key-abc123 --json # Find ID and describe pc api-key list pc api-key describe -i key-abc123 ``` Does not display the actual key value. **Description** Displays a list of all of the [target project's](/reference/cli/target-context) API keys, as found in Pinecone (regardless of whether they are stored locally by the CLI). Displays various details about each key, including name, ID, project ID, and roles. **Usage** ```bash theme={null} pc api-key list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :---------------------------------------------------------- | | `--id` | `-i` | Project ID (optional, uses target project if not specified) | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # List keys for target project pc api-key list # List for specific project pc api-key list -i proj-abc123 # JSON output pc api-key list --json ``` Does not display key values. **Description** Updates the name and roles of an API key. **Usage** ```bash theme={null} pc api-key update [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--id` | `-i` | API key ID (required) | | `--json` | `-j` | Output in JSON format | | `--name` | `-n` | New key name | | `--roles` | `-r` | Roles to assign | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} # Update name pc api-key update -i key-abc123 -n "new-name" # Update roles pc api-key update -i key-abc123 -r ProjectEditor # Verify changes pc api-key update -i key-abc123 -n "production-key" pc api-key describe -i key-abc123 ``` Cannot change the actual key. If you need a different key, create a new one. ### Config **Description** Lists all CLI configuration settings and their current values. Sensitive values like `api-key` are masked by default; use `--reveal` to see the full value. Hidden settings such as `environment` are included when `--all` is passed. **Usage** ```bash theme={null} pc config list [flags] ``` **Flags** | Long flag | Short flag | Description | | :--------- | :--------- | :-------------------------------------------------------- | | `--reveal` | | Reveal the full value for sensitive settings like api-key | | `--json` | `-j` | Output in JSON format | | `--all` | | Include hidden settings such as environment | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc config list pc config list --all pc config list --reveal pc config list --json ``` ```text CLI theme={null} KEY VALUE ENV VAR NAME ENV VAR OVERRIDE DESCRIPTION api-key ****abcd**** PINECONE_API_KEY false Default API key for authenticating with Pinecone color true Enable colored output ``` **Description** Gets the current value of a configuration setting. Valid keys are: `api-key`, `color`, `environment`. Sensitive values like `api-key` are masked by default; use `--reveal` to see the full value. **Usage** ```bash theme={null} pc config get [flags] ``` **Flags** | Long flag | Short flag | Description | | :--------- | :--------- | :-------------------------------------------------------- | | `--reveal` | | Reveal the full value for sensitive settings like api-key | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc config get api-key pc config get api-key --reveal pc config get environment pc config get color ``` **Description** Displays detailed information about a specific CLI configuration setting, including its current value, whether an environment variable is overriding it, and valid values. Valid keys are: `api-key`, `color`, `environment`. **Usage** ```bash theme={null} pc config describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :--------- | :--------- | :-------------------------------------------------------- | | `--reveal` | | Reveal the full value for sensitive settings like api-key | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc config describe api-key pc config describe color pc config describe color --json ``` ```text CLI theme={null} KEY api-key VALUE ****abcd**** ENV VAR NAME $PINECONE_API_KEY ENV VAR OVERRIDE false SENSITIVE true DESCRIPTION Default API key for authenticating with Pinecone ``` **Description** Sets a CLI configuration value. Valid keys are: `api-key`, `color`, `environment`. The value is persisted to the local config file. **Usage** ```bash theme={null} pc config set [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc config set api-key pcsk_... pc config set environment staging pc config set color false ``` **Description** Resets a CLI configuration value to its default. Valid keys are: `api-key`, `color`, `environment`. **Usage** ```bash theme={null} pc config unset [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | `-j` | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :---------- | :--------- | :---------------------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | | `--timeout` | | Timeout (default 60s, 0 to disable) | **Example** ```bash theme={null} pc config unset api-key pc config unset color ``` # CLI quickstart Source: https://docs.pinecone.io/reference/cli/quickstart Pinecone CLI quickstart for installing pc, authenticating, and managing indexes, vectors, and data imports directly from your terminal. The Pinecone CLI (`pc`) lets you manage Pinecone resources directly from your terminal. ## Install ```bash theme={null} brew tap pinecone-io/tap brew install pinecone-io/tap/pinecone ``` Pre-built binaries for macOS, Linux, and Windows are available on the [GitHub Releases page](https://github.com/pinecone-io/cli/releases). | Platform | Architectures | | :------- | :------------------------------------- | | macOS | Intel (x86\_64), Apple Silicon (ARM64) | | Linux | x86\_64, ARM64, i386 | | Windows | x86\_64, i386 | ## Authenticate ```bash theme={null} pc auth login ``` Visit the URL in your terminal to sign in. The CLI automatically sets your default organization and project. To target a different org/project: ```bash theme={null} pc target -o "my-org" -p "my-project" ``` For CI/CD or automation, you can also authenticate with a [service account](/reference/cli/authentication#service-account) or [API key](/reference/cli/authentication#api-key). ## Manage indexes ```bash theme={null} # List indexes pc index list # Create an index pc index create -n my-index -d 3 -m cosine -c aws -r us-east-1 # Get index details pc index describe -i my-index # Get index statistics pc index stats -i my-index ``` ## Work with vectors ```bash theme={null} # Upsert vectors (from file or inline JSON) pc index vector upsert -i my-index \ --body '{"vectors": [{"id": "vec1", "values": [0.1, 0.2, 0.3], "metadata": {"genre": "comedy"}}]}' # Import from a large dataset in object storage (S3, GCS, Azure) pc index import start -i my-index --uri s3://my-bucket/data/ # Check the progress of an import operation pc index import list --i my-index pc index import describe --i my-index --id import-123 # Query (vector can be inline or in a file) pc index vector query -i my-index \ --vector '[0.1, 0.2, 0.3]' \ --top-k 10 \ --include-metadata # Fetch by ID (from file or inline JSON) pc index vector fetch -i my-index --ids '["vec1","vec2"]' # List vector IDs from an index pc index vector list -i my-index ``` ## Manage namespaces ```bash theme={null} # List namespaces pc index namespace list -i my-index # Create a namespace pc index namespace create -i my-index --name tenant-a # Delete a namespace pc index namespace delete -i my-index --name tenant-a ``` ## Back up and restore ```bash theme={null} # Create a backup pc index backup create -i my-index --name "my-index-backup" # List backups (show index, backup name, backup ID, etc.) pc index backup list -i my-index # Restore from backup (by ID, not name) pc index restore -i c84725e5-5956-41ba-ab62-21ac7b5f2a2f -n restored-index ``` ## JSON output Add `-j` to any command for JSON output: ```bash theme={null} pc index list -j pc index describe -i my-index -j ``` ## Getting help Use `-h` or `--help` with any command to see available options: ```bash theme={null} pc -h pc index -h pc index create -h ``` ## Next steps * [Command reference](/reference/cli/command-reference) — Full list of commands and flags * [Authentication](/reference/cli/authentication) — Service accounts, API keys, and auth priority * [Target context](/reference/cli/target-context) — How org/project targeting works # CLI target context Source: https://docs.pinecone.io/reference/cli/target-context Pinecone CLI: The CLI's **target context** determines which organization and project your commands operate on. You must authenticate before setting target. The CLI's **target context** determines which organization and project your commands operate on. You must [authenticate](/reference/cli/authentication) before setting target context. ## Flags | Flag | Short | Default | Description | | ------------------- | ----- | ------- | --------------------------------------------------------------------------------- | | `--org` | `-o` | — | Target organization by name. Mutually exclusive with `--organization-id`. | | `--organization-id` | — | — | Target organization by ID. Mutually exclusive with `--org`. | | `--project` | `-p` | — | Target project by name. Mutually exclusive with `--project-id`. | | `--project-id` | — | — | Target project by ID. Mutually exclusive with `--project`. | | `--show` | `-s` | `false` | Show the current target context. | | `--clear` | — | `false` | Clear the stored target context. | | `--json` | `-j` | `false` | Output as JSON. In non-TTY environments (CI/CD, pipes), JSON output is automatic. | `--org` and `--organization-id` are mutually exclusive — use one or the other. The same applies to `--project` and `--project-id`. ## How operations use target context | Operation type | Scope | | -------------------------------- | ---------------------------------------- | | Control plane (indexes, backups) | Target project | | Data plane (vectors, namespaces) | Target project + specified index | | Admin API (organizations) | No target context needed | | Admin API (projects) | Target organization | | Admin API (API keys) | Target project (unless `--id` specified) | ## Target context by auth method ### User login After `pc auth login`, the CLI auto-targets your default organization and its first project. ```bash theme={null} # Change target pc target -o "my-org" -p "my-project" ``` ### Service account **Via CLI command:** After `pc auth configure --client-id --client-secret`, the CLI auto-targets the service account's organization. For the project: * If one project exists, it's auto-targeted * If multiple exist, you're prompted (or use `--project-id`) * If none exist, create one and target it manually **Via environment variables:** If using `PINECONE_CLIENT_ID` and `PINECONE_CLIENT_SECRET` without running `pc auth configure`, no target context is set automatically. Run `pc target` to set it. ```bash theme={null} # Change project (org is fixed to the service account's org) pc target -p "my-project" # Or select interactively pc target ``` ### API key When using an API key, control plane and data plane operations use the **key's org/project scope**, not the CLI's stored target context. The `pc target --show` output does not reflect what these operations actually use. API keys are scoped to a specific org and project and cannot access resources outside that scope. Admin API operations still use your user login or service account credentials (API keys can't authenticate Admin API calls). ## Managing target context ```bash theme={null} pc target --show # View current target pc target --clear # Clear target context ``` ### JSON mode and non-TTY environments Running `pc target --json` with no targeting flags returns the current target context as a JSON object. This is a local-state read — **no authentication is required**: ```bash theme={null} pc target --json ``` In non-TTY environments (CI/CD pipelines, shell pipes, scripts), JSON output is automatic — the same as passing `--json` explicitly. You do not need to add the flag in automation contexts. Use `--organization-id` and `--project-id` (instead of name flags) to set context reliably in scripts, since IDs are stable and unaffected by renames: ```bash theme={null} pc target --organization-id "org-abc123" --project-id "proj-xyz789" --json ``` # Pinecone SDKs overview Source: https://docs.pinecone.io/reference/pinecone-sdks Browse official Pinecone SDKs for Python, Node.js, Java, and Go, including the version mappings between SDK releases and API versions. ## Pinecone SDKs Official Pinecone SDKs provide convenient access to the [Pinecone APIs](/reference/api/introduction). ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and SDK versions are as follows: | | `2026-04` | `2025-10` | `2025-04` | `2025-01` | `2024-10` | `2024-07` | `2024-04` | | --------------------------------------------- | :---------- | :-------- | :-------- | :-------- | :-------- | :------------ | :-------- | | [Python SDK](/reference/sdks/python/overview) | v9.x | v8.x | v7.x | v6.x | v5.3.x | v5.0.x-v5.2.x | v4.x | | [Node.js SDK](/reference/sdks/node/overview) | v8.x | v7.x | v6.x | v5.x | v4.x | v3.x | v2.x | | [Java SDK](/reference/sdks/java/overview) | Coming soon | v6.x | v5.x | v4.x | v3.x | v2.x | v1.x | | [Go SDK](/reference/sdks/go/overview) | v6.x | v5.x | v4.x | v3.x | v2.x | v1.x | v0.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. The Java SDK targeting API version `2026-04` will be available soon. ## Limitations While Pinecone tracks read unit usage with decimal precision, the Pinecone API and SDKs round these values up to the nearest whole number in query, fetch, and list responses. For example, if a query uses 0.45 read units, the API and SDKs will report it as 1 read unit. For precise read unit reporting, see [index-level metrics](/guides/production/monitoring) or the organization-wide [Usage dashboard](/guides/manage-cost/monitor-usage-and-costs#monitor-organization-level-usage-and-costs). ## Community SDKs Find community-contributed SDKs for Pinecone. These libraries are not supported by Pinecone. * [Ruby SDK](https://github.com/ScotterC/pinecone) (contributed by [ScotterC](https://github.com/ScotterC)) * [Scala SDK](https://github.com/cequence-io/pinecone-scala) (contributed by [cequence-io](https://github.com/cequence-io)) * [PHP SDK](https://github.com/probots-io/pinecone-php) (contributed by [protobots-io](https://github.com/probots-io)) # Pinecone Go SDK Source: https://docs.pinecone.io/reference/sdks/go/overview Install and use the Pinecone Go SDK to manage indexes and namespaces, upsert vectors, run semantic search, and call the Admin and Inference APIs from Go. For installation instructions and usage examples, see the [Go SDK documentation](https://github.com/pinecone-io/go-pinecone). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/go-pinecone/issues). ## Requirements The Pinecone Go SDK requires a Go version with [modules](https://go.dev/wiki/Modules) support. ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and Go SDK versions are as follows: | API version | SDK version | | :---------- | :---------- | | `2026-04` | v6.x | | `2025-10` | v5.x | | `2025-04` | v4.x | | `2025-01` | v3.x | | `2024-10` | v2.x | | `2024-07` | v1.x | | `2024-04` | v0.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. ## Install To install the latest version of the [Go SDK](https://github.com/pinecone-io/go-pinecone), add a dependency to the current module: ```shell theme={null} go get github.com/pinecone-io/go-pinecone/v6/pinecone ``` To install a specific version of the Go SDK, run the following command: ```shell theme={null} go get github.com/pinecone-io/go-pinecone/v6/pinecone@ ``` To check your SDK version, run the following command: ```shell theme={null} go list -u -m all | grep go-pinecone ``` ## Upgrade Before upgrading to `v3.0.0` or later, update all relevant code to account for the breaking changes explained [here](/release-notes/2025#2025-02-07-4). Each major version carries its version number in the module path, so crossing a major requires updating the import path in every file that uses the SDK. For example, moving from `v4` to `v6` means changing: ```go theme={null} // before import "github.com/pinecone-io/go-pinecone/v4/pinecone" // after import "github.com/pinecone-io/go-pinecone/v6/pinecone" ``` Apart from the module path, `v5.0.0` and `v6.0.0` are backward compatible with the release lines before them. If you already have the Go SDK, upgrade to the latest version as follows: ```shell theme={null} go get -u github.com/pinecone-io/go-pinecone/v6/pinecone@latest ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance: ```Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) 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 manage organizations, projects, API keys, and [role-based access control](/guides/production/manage-rbac), initialize an `AdminClient` with [service account](/guides/organizations/manage-service-accounts) credentials instead: ```Go theme={null} package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v6/pinecone" ) func main() { ctx := context.Background() adminClient, err := pinecone.NewAdminClientWithContext(ctx, pinecone.NewAdminClientParams{ ClientId: os.Getenv("PINECONE_CLIENT_ID"), ClientSecret: os.Getenv("PINECONE_CLIENT_SECRET"), }) if err != nil { log.Fatalf("Failed to create AdminClient: %v", err) } } ``` # Reference Source: https://docs.pinecone.io/reference/sdks/go/reference Reference documentation for the Pinecone Go SDK, including client setup, types, and methods for managing indexes and vector data operations. # OpenTelemetry support Source: https://docs.pinecone.io/reference/sdks/java/open-telemetry Monitor Pinecone Java SDK operations with OpenTelemetry metrics for client latency, server processing time, and errors via Prometheus. The Pinecone Java SDK provides built-in support for capturing per-operation response metadata, making it straightforward to monitor your Pinecone usage with [OpenTelemetry](https://opentelemetry.io/) or any other observability system. With this feature, you can track client-side latency, server processing time, network overhead, error rates, and more for every data plane operation your application makes. ## How it all fits together The SDK's observability support is designed to be flexible. You don't need to adopt the entire observability stack at once -- start simple and add layers as your needs grow. Here are the components involved and how they relate to each other: * **Pinecone Java SDK**: Exposes a `ResponseMetadataListener` callback, a plain Java interface with no external dependencies. At its simplest, you can log the metadata to the console. No additional tools required. * **[OpenTelemetry](https://opentelemetry.io/) (OTel)**: An open standard and SDK for producing structured telemetry data (metrics, traces, logs). If you want standardized metrics that follow [semantic conventions](https://opentelemetry.io/docs/specs/semconv/database/database-spans/), you add the OTel SDK and wire it to the listener. This is optional. * **OTel Collector**: A vendor-neutral service that receives telemetry from your app and forwards it to a storage backend. Optional -- many setups export directly from the app to a backend. * **Prometheus**: A time-series database that stores metrics, making them queryable over time. One popular storage option. * **Grafana**: A visualization and dashboarding tool that queries Prometheus (or other backends) and displays charts and alerts. One popular visualization option. A common setup chains these together: ``` Your App (OTel SDK) → OTel Collector → Prometheus (storage) → Grafana (visualization) ``` This is just one example pipeline. You can substitute Datadog, New Relic, or any OTel-compatible backend. You can also skip OTel entirely and use [Micrometer](#example-micrometerprometheus), custom logging, or any approach that suits your stack. ## Response metadata listener The Java SDK captures response metadata through a `ResponseMetadataListener` -- a functional interface you provide when building the Pinecone client. The listener is called after each data plane operation completes (whether it succeeds or fails), and receives a `ResponseMetadata` object containing timing, status, and context information. The SDK itself has no OpenTelemetry dependency. You bring your own observability library and decide what to do with the metadata. ### Supported operations The following data plane operations are instrumented, for both synchronous (`Index`) and asynchronous (`AsyncIndex`) usage: | Operation | Description | | --------- | -------------------------- | | `upsert` | Insert or update vectors | | `query` | Search for similar vectors | | `fetch` | Retrieve vectors by ID | | `update` | Update vector metadata | | `delete` | Delete vectors | ### Available metadata Each `ResponseMetadata` object provides the following fields: | Method | Description | OTel attribute | | ------------------------ | -------------------------------------------------- | ------------------------- | | `getOperationName()` | Operation type (e.g., `upsert`, `query`) | `db.operation.name` | | `getIndexName()` | Pinecone index name | `pinecone.index_name` | | `getNamespace()` | Namespace (empty string if default) | `db.namespace` | | `getServerAddress()` | Pinecone server host | `server.address` | | `getClientDurationMs()` | Total round-trip time in ms (always available) | -- | | `getServerDurationMs()` | Server processing time in ms (may be `null`) | -- | | `getNetworkOverheadMs()` | Client minus server duration in ms (may be `null`) | -- | | `getStatus()` | `"success"` or `"error"` | `status` | | `getGrpcStatusCode()` | Raw gRPC status code (e.g., `OK`, `UNAVAILABLE`) | `db.response.status_code` | | `getErrorType()` | Error category, or `null` if successful | `error.type` | Possible `errorType` values: `validation`, `connection`, `server`, `rate_limit`, `timeout`, `auth`, `not_found`, `unknown`. ### Recommended metrics If you're recording OTel metrics, the SDK example project uses these metric names, which follow [OTel semantic conventions for database clients](https://opentelemetry.io/docs/specs/semconv/database/database-spans/): | Metric | Type | Unit | Description | | ------------------------------------- | --------- | ---- | ------------------------------- | | `db.client.operation.duration` | Histogram | ms | Client-measured round-trip time | | `pinecone.server.processing.duration` | Histogram | ms | Server processing time | | `db.client.operation.count` | Counter | -- | Total number of operations | ## Quick start: Simple logging The simplest way to use the listener is to log the metadata directly. This requires no additional dependencies beyond the Pinecone SDK: ```java theme={null} import io.pinecone.clients.Pinecone; Pinecone client = new Pinecone.Builder("PINECONE_API_KEY") .withResponseMetadataListener(metadata -> { System.out.printf("Operation: %s | Client: %dms | Server: %sms | Network: %sms | Status: %s%n", metadata.getOperationName(), metadata.getClientDurationMs(), metadata.getServerDurationMs(), metadata.getNetworkOverheadMs(), metadata.getStatus()); }) .build(); ``` Once configured, every data plane operation automatically triggers the listener: ```java theme={null} Index index = client.getIndexConnection("my-index"); index.upsert("id-1", Arrays.asList(0.1f, 0.2f, 0.3f)); // Output: Operation: upsert | Client: 47ms | Server: 40ms | Network: 7ms | Status: success ``` ## Quick start: OpenTelemetry integration To record structured metrics with OpenTelemetry, add the OTel SDK dependencies and wire a metrics recorder to the listener. ### 1. Add dependencies Add the following to your `pom.xml`: ```xml theme={null} io.pinecone pinecone-client LATEST io.opentelemetry opentelemetry-sdk io.opentelemetry opentelemetry-sdk-metrics io.opentelemetry opentelemetry-exporter-otlp io.opentelemetry opentelemetry-bom 1.35.0 pom import ``` ### 2. Create a metrics recorder The SDK's [example project](https://github.com/pinecone-io/pinecone-java-client/tree/main/examples/java-otel-metrics) includes a reusable `PineconeMetricsRecorder` class you can copy into your project. It implements `ResponseMetadataListener` and records all three recommended metrics with proper OTel attributes: ```java theme={null} import io.opentelemetry.api.common.AttributeKey; import io.opentelemetry.api.common.Attributes; import io.opentelemetry.api.common.AttributesBuilder; import io.opentelemetry.api.metrics.LongCounter; import io.opentelemetry.api.metrics.LongHistogram; import io.opentelemetry.api.metrics.Meter; import io.pinecone.configs.ResponseMetadata; import io.pinecone.configs.ResponseMetadataListener; public class PineconeMetricsRecorder implements ResponseMetadataListener { private static final AttributeKey DB_SYSTEM = AttributeKey.stringKey("db.system"); private static final AttributeKey DB_OPERATION_NAME = AttributeKey.stringKey("db.operation.name"); private static final AttributeKey DB_NAMESPACE = AttributeKey.stringKey("db.namespace"); private static final AttributeKey PINECONE_INDEX_NAME = AttributeKey.stringKey("pinecone.index_name"); private static final AttributeKey SERVER_ADDRESS = AttributeKey.stringKey("server.address"); private static final AttributeKey STATUS = AttributeKey.stringKey("status"); private static final AttributeKey ERROR_TYPE = AttributeKey.stringKey("error.type"); private final LongHistogram clientDurationHistogram; private final LongHistogram serverDurationHistogram; private final LongCounter operationCounter; public PineconeMetricsRecorder(Meter meter) { this.clientDurationHistogram = meter.histogramBuilder("db.client.operation.duration") .setDescription("Duration of Pinecone operations from client perspective") .setUnit("ms") .ofLongs() .build(); this.serverDurationHistogram = meter.histogramBuilder("pinecone.server.processing.duration") .setDescription("Server processing time from x-pinecone-response-duration-ms header") .setUnit("ms") .ofLongs() .build(); this.operationCounter = meter.counterBuilder("db.client.operation.count") .setDescription("Total number of Pinecone operations") .setUnit("{operation}") .build(); } @Override public void onResponse(ResponseMetadata metadata) { AttributesBuilder attributesBuilder = Attributes.builder() .put(DB_SYSTEM, "pinecone") .put(DB_OPERATION_NAME, metadata.getOperationName()) .put(PINECONE_INDEX_NAME, metadata.getIndexName()) .put(SERVER_ADDRESS, metadata.getServerAddress()) .put(STATUS, metadata.getStatus()); String namespace = metadata.getNamespace(); if (namespace != null && !namespace.isEmpty()) { attributesBuilder.put(DB_NAMESPACE, namespace); } if (!metadata.isSuccess() && metadata.getErrorType() != null) { attributesBuilder.put(ERROR_TYPE, metadata.getErrorType()); } Attributes attributes = attributesBuilder.build(); clientDurationHistogram.record(metadata.getClientDurationMs(), attributes); Long serverDuration = metadata.getServerDurationMs(); if (serverDuration != null) { serverDurationHistogram.record(serverDuration, attributes); } operationCounter.add(1, attributes); } } ``` ### 3. Wire it into the Pinecone client Initialize the OTel SDK, create the recorder, and pass it to the Pinecone client builder: ```java theme={null} import io.opentelemetry.api.metrics.Meter; import io.opentelemetry.sdk.OpenTelemetrySdk; import io.opentelemetry.sdk.metrics.SdkMeterProvider; import io.opentelemetry.sdk.metrics.export.PeriodicMetricReader; import io.opentelemetry.exporter.otlp.metrics.OtlpGrpcMetricExporter; import io.pinecone.clients.Pinecone; // Set up OTel with OTLP exporter OtlpGrpcMetricExporter exporter = OtlpGrpcMetricExporter.builder() .setEndpoint("http://localhost:4317") .build(); SdkMeterProvider meterProvider = SdkMeterProvider.builder() .registerMetricReader(PeriodicMetricReader.builder(exporter).build()) .build(); OpenTelemetrySdk openTelemetry = OpenTelemetrySdk.builder() .setMeterProvider(meterProvider) .build(); // Create the metrics recorder Meter meter = openTelemetry.getMeter("pinecone.client"); PineconeMetricsRecorder recorder = new PineconeMetricsRecorder(meter); // Build the Pinecone client with the recorder Pinecone client = new Pinecone.Builder("PINECONE_API_KEY") .withResponseMetadataListener(recorder) .build(); // Use the client normally -- metrics are recorded automatically Index index = client.getIndexConnection("my-index"); index.upsert("id-1", Arrays.asList(0.1f, 0.2f, 0.3f)); index.query(3, Arrays.asList(0.1f, 0.2f, 0.3f)); ``` For a complete runnable example with Docker Compose, Prometheus, and Grafana, see the [java-otel-metrics example project](https://github.com/pinecone-io/pinecone-java-client/tree/main/examples/java-otel-metrics) in the SDK repository. ## Example: Micrometer/Prometheus If your application uses [Micrometer](https://micrometer.io/) (common in Spring Boot), you can wire the listener to Micrometer instead of the OTel SDK: ```java theme={null} import io.micrometer.core.instrument.MeterRegistry; import io.micrometer.core.instrument.Timer; import io.pinecone.clients.Pinecone; import java.util.concurrent.TimeUnit; Pinecone client = new Pinecone.Builder("PINECONE_API_KEY") .withResponseMetadataListener(metadata -> { Timer.builder("pinecone.client.duration") .tag("operation", metadata.getOperationName()) .tag("index", metadata.getIndexName()) .tag("status", metadata.getStatus()) .register(meterRegistry) .record(metadata.getClientDurationMs(), TimeUnit.MILLISECONDS); }) .build(); ``` ## Visualizing metrics Once your metrics are flowing to a backend, you can build dashboards to monitor your Pinecone operations. If you're using Prometheus and Grafana, here are some useful queries: **P50 and P95 client latency:** ```promql theme={null} histogram_quantile(0.5, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le)) histogram_quantile(0.95, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le)) ``` **P95 latency by operation type:** ```promql theme={null} histogram_quantile(0.95, sum(rate(db_client_operation_duration_milliseconds_bucket[5m])) by (le, db_operation_name)) ``` **Operation count by type:** ```promql theme={null} sum by (db_operation_name) (db_client_operation_count_total) ``` ## Understanding the latency breakdown The `ResponseMetadata` object provides three timing values that help you pinpoint the source of latency issues: | Component | Method | What it measures | | ---------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | Client duration | `getClientDurationMs()` | Total round-trip time from request start to response completion. Always available. | | Server duration | `getServerDurationMs()` | Time the Pinecone backend spent processing the request. Extracted from the `x-pinecone-response-duration-ms` response header. May be `null`. | | Network overhead | `getNetworkOverheadMs()` | The difference: client duration minus server duration. Includes network latency, serialization, and deserialization. May be `null`. | Use these values to diagnose performance issues: * **High server duration**: The bottleneck is on the Pinecone backend. Consider optimizing your query (e.g., reducing `topK`, using metadata filters), or check the [Pinecone status page](https://status.pinecone.io/). * **High network overhead**: The bottleneck is in the network path between your application and Pinecone. Consider deploying your application closer to your index's cloud region, or check for network issues. ## Limitations * **Data plane operations only.** Control plane operations (e.g., creating or deleting indexes) are not currently instrumented. * **Bulk import operations** are not yet instrumented. * **Server duration may be unavailable.** The `getServerDurationMs()` method returns `null` if the `x-pinecone-response-duration-ms` header is not present in the response. * **Synchronous callback.** The listener is called synchronously after the gRPC response is received. Keep implementations lightweight and non-blocking to avoid adding latency to your operations. For heavy processing, queue the metadata for async handling. * **Exceptions are swallowed.** Exceptions thrown by the listener are logged but do not affect the operation result. ## Best practices * **Keep listeners lightweight.** Record metrics or enqueue work -- don't do I/O or heavy computation in the callback. * **Follow OTel semantic conventions.** Use the attribute names shown in the [recommended metrics](#recommended-metrics) table for interoperability with standard dashboards and tooling. * **Monitor both client and server duration.** Tracking both lets you separate Pinecone backend performance from network conditions. * **Set alerts on error rates.** Use the `status` and `error.type` attributes to build alerts for elevated error rates across operations. # Pinecone Java SDK Source: https://docs.pinecone.io/reference/sdks/java/overview Install and use the Pinecone Java SDK to manage indexes and namespaces, upsert vectors, run semantic search, and call the Admin and Inference APIs from Java. For installation instructions and usage examples, see the [Pinecone Java SDK documentation](https://github.com/pinecone-io/pinecone-java-client). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-java-client/issues). ## Requirements The Pinecone Java SDK requires Java 1.8 or later. ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and Java SDK versions are as follows: | API version | SDK version | | :---------- | :---------- | | `2025-04` | v5.x | | `2025-01` | v4.x | | `2024-10` | v3.x | | `2024-07` | v2.x | | `2024-04` | v1.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. ## Install To install the latest version of the [Java SDK](https://github.com/pinecone-io/pinecone-java-client), add a dependency to the current module: ```shell Java theme={null} # Maven io.pinecone pinecone-client 5.0.0 # Gradle implementation "io.pinecone:pinecone-client:5.0.0" ``` Alternatively, you can download the standalone uberjar [pinecone-client-4.0.0-all.jar](https://repo1.maven.org/maven2/io/pinecone/pinecone-client/4.0.0/pinecone-client-4.0.0-all.jar), which bundles the Pinecone SDK and all dependencies together. You can include this in your classpath like you do with any third-party JAR without having to obtain the `pinecone-client` dependencies separately. ## Upgrade Before upgrading to `v4.0.0`, update all relevant code to account for the breaking changes explained [here](/release-notes/2025#2025-02-07-3). If you are already using the Java SDK, upgrade the dependency in the current module to the latest version: ```shell Java theme={null} # Maven io.pinecone pinecone-client 5.0.0 # Gradle implementation "io.pinecone:pinecone-client:5.0.0" ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance: ```Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class InitializeClientExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); } } ``` ## Observability The Java SDK supports capturing per-operation response metadata for all data plane operations, including client-side latency, server processing time, network overhead, and error details. You can use this metadata with [OpenTelemetry](https://opentelemetry.io/), Micrometer, or any other observability system to monitor your Pinecone usage in production. For setup instructions and examples, see [OpenTelemetry support](/reference/sdks/java/open-telemetry). # Reference Source: https://docs.pinecone.io/reference/sdks/java/reference Reference documentation for the Pinecone Java SDK, including client setup, types, and methods for managing indexes and vector data operations. # Pinecone Node.js SDK Source: https://docs.pinecone.io/reference/sdks/node/overview Install and use the Pinecone Node.js and TypeScript SDK to manage indexes, upsert vectors, run semantic search, and call the Admin and Inference APIs. For installation instructions, usage examples, and reference information, see the [Pinecone Node.js SDK documentation](https://sdk.pinecone.io/typescript/). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-ts-client/issues). ## Requirements The Pinecone Node SDK requires TypeScript 4.1 or later and Node 18.x or later. ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and Node.js SDK versions are as follows: | API version | SDK version | | :---------- | :---------- | | `2026-04` | v8.x | | `2025-10` | v7.x | | `2025-04` | v6.x | | `2025-01` | v5.x | | `2024-10` | v4.x | | `2024-07` | v3.x | | `2024-04` | v2.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. ## Install To install the latest version of the [Node.js SDK](https://github.com/pinecone-io/pinecone-ts-client), written in TypeScript, run the following command: ```Shell theme={null} npm install @pinecone-database/pinecone ``` To check your SDK version, run the following command: ```Shell theme={null} npm list | grep @pinecone-database/pinecone ``` ## Upgrade If you already have the Node.js SDK, upgrade to the latest version as follows: ```Shell theme={null} npm install @pinecone-database/pinecone@latest ``` ## Initialize Once installed, you can import the library and then use an [API key](/guides/projects/manage-api-keys) to initialize a client instance: ```JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); ``` To manage organizations, projects, API keys, and [role-based access control](/guides/production/manage-rbac), initialize an `AdminClient` with [service account](/guides/organizations/manage-service-accounts) credentials instead. This requires v8.2.0 or later: ```JavaScript theme={null} import { AdminClient } from '@pinecone-database/pinecone'; // Reads PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET from the environment const admin = new AdminClient(); ``` You can also pass `clientId` and `clientSecret` directly to the constructor instead of setting environment variables. ## Proxy configuration If your network setup requires you to interact with Pinecone through a proxy, you can pass a custom `ProxyAgent` from the [`undici` library](https://undici.nodejs.org/#/). Below is an example of how to construct an `undici` `ProxyAgent` that routes network traffic through a [`mitm` proxy server](https://mitmproxy.org/) while hitting Pinecone's `/indexes` endpoint. The following strategy relies on Node's native [`fetch`](https://nodejs.org/docs/latest/api/globals.html#fetch) implementation, released in Node v16 and stabilized in Node v21. If you are running Node versions 18-21, you may experience issues stemming from the instability of the feature. There are currently no known issues related to proxying in Node v18+. ```JavaScript JavaScript theme={null} import { Pinecone, type PineconeConfiguration, } from '@pinecone-database/pinecone'; import { Dispatcher, ProxyAgent } from 'undici'; import * as fs from 'fs'; const cert = fs.readFileSync('path/to/mitmproxy-ca-cert.pem'); const client = new ProxyAgent({ uri: 'https://your-proxy.com', requestTls: { port: 'YOUR_PROXY_SERVER_PORT', ca: cert, host: 'YOUR_PROXY_SERVER_HOST', }, }); const customFetch = ( input: string | URL | Request, init: RequestInit | undefined ) => { return fetch(input, { ...init, dispatcher: client as Dispatcher, keepalive: true, # optional }); }; const config: PineconeConfiguration = { apiKey: 'YOUR_API_KEY', fetchApi: customFetch, }; const pc = new Pinecone(config); const indexes = async () => { return await pc.listIndexes(); }; indexes().then((response) => { console.log('My indexes: ', response); }); ``` # Reference Source: https://docs.pinecone.io/reference/sdks/node/reference Reference documentation for the Pinecone Node.js SDK, including client setup, types, and methods for managing indexes and vector data operations. # Pinecone Python SDK Source: https://docs.pinecone.io/reference/sdks/python/overview Install and use the Pinecone SDK for Pinecone Python SDK: auth, typed clients, and API operations. For installation instructions, usage examples, and. For installation instructions, usage examples, and reference information, see the [Pinecone Python SDK documentation](https://sdk.pinecone.io/python/). To report an issue or request a feature, [file an issue on GitHub](https://github.com/pinecone-io/pinecone-python-client/issues). The Pinecone Python SDK is distributed on PyPI using the package name `pinecone`. By default, the `pinecone` package has a minimal set of dependencies and interacts with Pinecone via HTTP requests. However, you can install the following extras to unlock additional functionality: * `pinecone[grpc]` adds dependencies on `grpcio` and related libraries needed to run data operations such as upserts and queries over [gRPC](https://grpc.io/) for a modest performance improvement. * `pinecone[asyncio]` adds a dependency on `aiohttp` and enables usage of `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). For more details, see [Async requests](#async-requests). ## Requirements The Pinecone Python SDK requires Python 3.9 or later. It has been tested with CPython versions from 3.9 to 3.13. ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and Python SDK versions are as follows: | API version | SDK version | | :---------- | :------------ | | `2025-04` | v7.x | | `2025-01` | v6.x | | `2024-10` | v5.3.x | | `2024-07` | v5.0.x-v5.2.x | | `2024-04` | v4.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. ## Install To install the latest version of the [Python SDK](https://github.com/pinecone-io/pinecone-python-client), run the following command: ```shell theme={null} # Install the latest version pip install pinecone # Install the latest version with gRPC extras pip install "pinecone[grpc]" # Install the latest version with asyncio extras pip install "pinecone[asyncio]" ``` To install a specific version of the Python SDK, run the following command: ```shell pip theme={null} # Install a specific version pip install pinecone== # Install a specific version with gRPC extras pip install "pinecone[grpc]"== # Install a specific version with asyncio extras pip install "pinecone[asyncio]"== ``` To check your SDK version, run the following command: ```shell pip theme={null} pip show pinecone ``` To use the [Inference API](/reference/api/introduction#inference), you must be on version 5.0.0 or later. ### Install the Pinecone Assistant Python plugin As of Python SDK v7.0.0, the `pinecone-plugin-assistant` package is included by default. It is only necessary to install the package if you are using a version of the Python SDK prior to v7.0.0. ```shell HTTP theme={null} pip install --upgrade pinecone pinecone-plugin-assistant ``` ## Upgrade Before upgrading to `v6.0.0`, update all relevant code to account for the breaking changes explained [here](https://github.com/pinecone-io/pinecone-python-client/blob/main/docs/upgrading.md). Also, make sure to upgrade using the `pinecone` package name instead of `pinecone-client`; upgrading with the latter will not work as of `v6.0.0`. If you already have the Python SDK, upgrade to the latest version as follows: ```shell theme={null} # Upgrade to the latest version pip install pinecone --upgrade # Upgrade to the latest version with gRPC extras pip install "pinecone[grpc]" --upgrade # Upgrade to the latest version with asyncio extras pip install "pinecone[asyncio]" --upgrade ``` ## Initialize Once installed, you can import the library and then use an [API key](/guides/projects/manage-api-keys) to initialize a client instance: ```Python HTTP theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` ```python gRPC theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` When [creating an index](/guides/index-data/create-an-index), import the `ServerlessSpec` or `PodSpec` class as well: ```Python Serverless index theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ) ) ``` ```Python Pod-based index theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import PodSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=PodSpec( environment="us-west-1-gcp", pod_type="p1.x1", pods=1 ) ) ``` ## Proxy configuration If your network setup requires you to interact with Pinecone through a proxy, you will need to pass additional configuration using optional keyword parameters: * `proxy_url`: The location of your proxy. This could be an HTTP or HTTPS URL depending on your proxy setup. * `proxy_headers`: Accepts a python dictionary which can be used to pass any custom headers required by your proxy. If your proxy is protected by authentication, use this parameter to pass basic authentication headers with a digest of your username and password. The `make_headers` utility from `urllib3` can be used to help construct the dictionary. **Note:** Not supported with Asyncio. * `ssl_ca_certs`: By default, the client will perform SSL certificate verification using the CA bundle maintained by Mozilla in the [`certifi`](https://pypi.org/project/certifi/) package. If your proxy is using self-signed certicates, use this parameter to specify the path to the certificate (PEM format). * `ssl_verify`: SSL verification is enabled by default, but it is disabled when set to `False`. It is not recommened to go into production with SSL verification disabled. ```python HTTP theme={null} from pinecone import Pinecone import urllib3 from urllib3.util import make_headers pc = Pinecone( api_key="YOUR_API_KEY", proxy_url='https://your-proxy.com', proxy_headers=make_headers(proxy_basic_auth='username:password'), ssl_ca_certs='path/to/cert-bundle.pem' ) ``` ```python gRPC theme={null} from pinecone.grpc import PineconeGRPC as Pinecone import urllib3 from urllib3.util import make_headers pc = Pinecone( api_key="YOUR_API_KEY", proxy_url='https://your-proxy.com', proxy_headers=make_headers(proxy_basic_auth='username:password'), ssl_ca_certs='path/to/cert-bundle.pem' ) ``` ```python asyncio theme={null} import asyncio from pinecone import PineconeAsyncio async def main(): async with PineconeAsyncio( api_key="YOUR_API_KEY", proxy_url='https://your-proxy.com', ssl_ca_certs='path/to/cert-bundle.pem' ) as pc: # Do async things await pc.list_indexes() asyncio.run(main()) ``` ## Async requests Pinecone Python SDK versions 6.0.0 and later provide `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). Asyncio support makes it possible to use Pinecone with modern async web frameworks such as [FastAPI](https://fastapi.tiangolo.com/), [Quart](https://quart.palletsprojects.com/en/latest/), and [Sanic](https://sanic.dev/en/), and should significantly increase the efficiency of running requests in parallel. Use the [`PineconeAsyncio`](https://sdk.pinecone.io/python/asyncio.html) class to create and manage indexes and the [`IndexAsyncio`](https://sdk.pinecone.io/python/asyncio.html#pinecone.db_data.IndexAsyncio) class to read and write index data. To ensure that sessions are properly closed, use the `async with` syntax when creating `PineconeAsyncio` and `IndexAsyncio` objects. ```python Manage indexes theme={null} # pip install "pinecone[asyncio]" import asyncio from pinecone import PineconeAsyncio, ServerlessSpec async def main(): async with PineconeAsyncio(api_key="YOUR_API_KEY") as pc: if not await pc.has_index(index_name): desc = await pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ), deletion_protection="disabled", tags={ "environment": "development" } ) asyncio.run(main()) ``` ```python Read and write index data theme={null} # pip install "pinecone[asyncio]" import asyncio from pinecone import Pinecone async def main(): pc = Pinecone(api_key="YOUR_API_KEY") async with pc.IndexAsyncio(host="INDEX_HOST") as idx: await idx.upsert_records( namespace="example-namespace", records=[ { "id": "1", "title": "The Great Gatsby", "author": "F. Scott Fitzgerald", "description": "The story of the mysteriously wealthy Jay Gatsby and his love for the beautiful Daisy Buchanan.", "year": 1925, }, { "id": "2", "title": "To Kill a Mockingbird", "author": "Harper Lee", "description": "A young girl comes of age in the segregated American South and witnesses her father's courageous defense of an innocent black man.", "year": 1960, }, { "id": "3", "title": "1984", "author": "George Orwell", "description": "In a dystopian future, a totalitarian regime exercises absolute control through pervasive surveillance and propaganda.", "year": 1949, }, ] ) asyncio.run(main()) ``` ## Query across namespaces Each query is limited to a single [namespace](/guides/index-data/indexing-overview#namespaces). However, the Pinecone Python SDK provides a `query_namespaces` utility method to run a query in parallel across multiple namespaces in an index and then merge the result sets into a single ranked result set with the `top_k` most relevant results. The `query_namespaces` method accepts most of the same arguments as `query` with the addition of a required `namespaces` parameter. When using the Python SDK without gRPC extras, to get good performance, it is important to set values for the `pool_threads` and `connection_pool_maxsize` properties on the index client. The `pool_threads` setting is the number of threads available to execute requests, while `connection_pool_maxsize` is the number of cached http connections that will be held. Since these tasks are not computationally heavy and are mainly i/o bound, it should be okay to have a high ratio of threads to cpus. The combined results include the sum of all read unit usage used to perform the underlying queries for each namespace. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index( name="docs-example", pool_threads=50, # <-- make sure to set these connection_pool_maxsize=50, # <-- make sure to set these ) query_vec = [ 0.1, ...] # an embedding vector with same dimension as the index combined_results = index.query_namespaces( vector=query_vec, namespaces=['ns1', 'ns2', 'ns3', 'ns4'], metric="cosine", top_k=10, include_values=False, include_metadata=True, filter={"genre": { "$eq": "comedy" }}, show_progress=False, ) for scored_vec in combined_results.matches: print(scored_vec) print(combined_results.usage) ``` When using the Python SDK with gRPC extras, there is no need to set the `connection_pool_maxsize` because grpc makes efficient use of open connections by default. ```python Python theme={null} from pinecone.grpc import PineconeGRPC pc = PineconeGRPC(api_key="YOUR_API_KEY") index = pc.Index( name="docs-example", pool_threads=50, # <-- make sure to set this ) query_vec = [ 0.1, ...] # an embedding vector with same dimension as the index combined_results = index.query_namespaces( vector=query_vec, namespaces=['ns1', 'ns2', 'ns3', 'ns4'], metric="cosine", top_k=10, include_values=False, include_metadata=True, filter={"genre": { "$eq": "comedy" }}, show_progress=False, ) for scored_vec in combined_results.matches: print(scored_vec) print(combined_results.usage) ``` ## Upsert from a dataframe To quickly ingest data when using the [Python SDK](/reference/sdks/python/overview), use the `upsert_from_dataframe` method. The method includes retry logic and`batch_size`, and is performant especially with Parquet file data sets. The following example upserts the `uora_all-MiniLM-L6-bm25` dataset as a dataframe. ```Python Python theme={null} from pinecone import Pinecone, ServerlessSpec from pinecone_datasets import list_datasets, load_dataset pc = Pinecone(api_key="API_KEY") dataset = load_dataset("quora_all-MiniLM-L6-bm25") pc.create_index( name="docs-example", dimension=384, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ) ) # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.upsert_from_dataframe(dataset.drop(columns=["blob"])) ``` # Reference Source: https://docs.pinecone.io/reference/sdks/python/reference Reference documentation for the Pinecone Python SDK, including client setup, types, and methods for managing indexes and vector data operations. # Spark-Pinecone connector Source: https://docs.pinecone.io/reference/tools/pinecone-spark-connector Pinecone data tools: Use the connector to efficiently create, ingest, and update vector embeddings at scale with Databricks and Pinecone. Use the [`spark-pinecone` connector](https://github.com/pinecone-io/spark-pinecone/) to efficiently create, ingest, and update [vector embeddings](https://www.pinecone.io/learn/vector-embeddings/) at scale with [Databricks and Pinecone](/integrations/databricks). ## Install the Spark-Pinecone connector 1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster). 2. Configure the library as follows: 1. Select **File path/S3** as the **Library Source**. 2. Enter the S3 URI for the Pinecone assembly JAR file: ``` s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar ``` Databricks platform users must use the Pinecone assembly jar listed above to ensure that the proper dependecies are installed. 3. Click **Install**. 1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster). 2. Configure the library as follows: 1. Select **File path/S3** as the **Library Source**. 2. Enter the S3 URI for the Pinecone assembly JAR file: ``` s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar ``` 3. Click **Install**. 1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster). 2. Configure the library as follows: 1. [Download the Pinecone assembly JAR file](https://repo1.maven.org/maven2/io/pinecone/spark-pinecone_2.12/1.1.0/). 2. Select **Workspace** as the **Library Source**. 3. Upload the JAR file. 4. Click **Install**. ## Batch upsert To batch upsert embeddings to Pinecone: ```python Python theme={null} from pyspark import SparkConf from pyspark.sql import SparkSession from pyspark.sql.types import StructType, StructField, ArrayType, FloatType, StringType, LongType # Your API key and index name api_key = "PINECONE_API_KEY" index_name = "PINECONE_INDEX_NAME" source_tag = "PINECONE_SOURCE_TAG" COMMON_SCHEMA = StructType([ StructField("id", StringType(), False), StructField("namespace", StringType(), True), StructField("values", ArrayType(FloatType(), False), False), StructField("metadata", StringType(), True), StructField("sparse_values", StructType([ StructField("indices", ArrayType(LongType(), False), False), StructField("values", ArrayType(FloatType(), False), False) ]), True) ]) # Initialize Spark spark = SparkSession.builder.getOrCreate() # Read the file and apply the schema df = spark.read \ .option("multiLine", value = True) \ .option("mode", "PERMISSIVE") \ .schema(COMMON_SCHEMA) \ .json("src/test/resources/sample.jsonl") # Show if the read was successful df.show() # Write the dataFrame to Pinecone in batches df.write \ .option("pinecone.apiKey", api_key) \ .option("pinecone.indexName", index_name) \ .option("pinecone.sourceTag", source_tag) \ .format("io.pinecone.spark.pinecone.Pinecone") \ .mode("append") \ .save() ``` ```scala Scala theme={null} import io.pinecone.spark.pinecone.{COMMON_SCHEMA, PineconeOptions} import org.apache.spark.SparkConf import org.apache.spark.sql.{SaveMode, SparkSession} object MainApp extends App { // Your API key and index name val apiKey = "PINECONE_API_KEY" val indexName = "PINECONE_INDEX_NAME" val sourceTag = "PINECONE_SOURCE_TAG" // Configure Spark to run locally with all available cores val conf = new SparkConf() .setMaster("local[*]") // Create a Spark session with the defined configuration val spark = SparkSession.builder().config(conf).getOrCreate() // Read the JSON file into a DataFrame, applying the COMMON_SCHEMA val df = spark.read .option("multiLine", value = true) .option("mode", "PERMISSIVE") .schema(COMMON_SCHEMA) .json("src/test/resources/sample.jsonl") // path to sample.jsonl // Define Pinecone options as a Map val pineconeOptions = Map( PineconeOptions.PINECONE_API_KEY_CONF -> apiKey, PineconeOptions.PINECONE_INDEX_NAME_CONF -> indexName, PineconeOptions.PINECONE_SOURCE_TAG_CONF -> sourceTag ) // Show if the read was successful df.show(df.count().toInt) // Write the DataFrame to Pinecone using the defined options in batches df.write .options(pineconeOptions) .format("io.pinecone.spark.pinecone.Pinecone") .mode(SaveMode.Append) .save() } ``` For a guide on how to set up batch upserts, refer to the [Databricks integration page](/integrations/databricks#setup-guide). ## Stream upsert To stream upsert embeddings to Pinecone: ```python Python theme={null} from pyspark.sql import SparkSession from pyspark.sql.types import StructType, StructField, ArrayType, FloatType, StringType, LongType import os # Your API key and index name api_key = "PINECONE_API_KEY" index_name = "PINECONE_INDEX_NAME" source_tag = "PINECONE_SOURCE_TAG" COMMON_SCHEMA = StructType([ StructField("id", StringType(), False), StructField("namespace", StringType(), True), StructField("values", ArrayType(FloatType(), False), False), StructField("metadata", StringType(), True), StructField("sparse_values", StructType([ StructField("indices", ArrayType(LongType(), False), False), StructField("values", ArrayType(FloatType(), False), False) ]), True) ]) # Initialize Spark session spark = SparkSession.builder \ .appName("StreamUpsertExample") \ .config("spark.sql.shuffle.partitions", 3) \ .master("local") \ .getOrCreate() # Read the stream of JSON files, applying the schema from the input directory lines = spark.readStream \ .option("multiLine", True) \ .option("mode", "PERMISSIVE") \ .schema(COMMON_SCHEMA) \ .json("path/to/input/directory/") # Write the stream to Pinecone using the defined options upsert = lines.writeStream \ .format("io.pinecone.spark.pinecone.Pinecone") \ .option("pinecone.apiKey", api_key) \ .option("pinecone.indexName", index_name) \ .option("pinecone.sourceTag", source_tag) \ .option("checkpointLocation", "path/to/checkpoint/dir") \ .outputMode("append") \ .start() upsert.awaitTermination() ``` ```scala Scala theme={null} import io.pinecone.spark.pinecone.{COMMON_SCHEMA, PineconeOptions} import org.apache.spark.SparkConf import org.apache.spark.sql.{SaveMode, SparkSession} object MainApp extends App { // Your API key and index name val apiKey = "PINECONE_API_KEY" val indexName = "PINECONE_INDEX_NAME" // Create a Spark session val spark = SparkSession.builder() .appName("StreamUpsertExample") .config("spark.sql.shuffle.partitions", 3) .master("local") .getOrCreate() // Read the JSON files into a DataFrame, applying the COMMON_SCHEMA from input directory val lines = spark.readStream .option("multiLine", value = true) .option("mode", "PERMISSIVE") .schema(COMMON_SCHEMA) .json("path/to/input/directory/") // Define Pinecone options as a Map val pineconeOptions = Map( PineconeOptions.PINECONE_API_KEY_CONF -> System.getenv("PINECONE_API_KEY"), PineconeOptions.PINECONE_INDEX_NAME_CONF -> System.getenv("PINECONE_INDEX"), PineconeOptions.PINECONE_SOURCE_TAG_CONF -> System.getenv("PINECONE_SOURCE_TAG") ) // Write the stream to Pinecone using the defined options val upsert = lines .writeStream .format("io.pinecone.spark.pinecone.Pinecone") .options(pineconeOptions) .option("checkpointLocation", "path/to/checkpoint/dir") .outputMode("append") .start() upsert.awaitTermination() } ``` ## Learn more * [Spark-Pinecone connector setup guide](/integrations/databricks#setup-guide) * [GitHub](https://github.com/pinecone-io/spark-pinecone) # Notebooks Source: https://docs.pinecone.io/examples/notebooks Runnable Colab notebooks covering semantic search, lexical search, hybrid search, RAG, embeddings, reranking, and data ingestion with Pinecone.

Search

Retrieval-augmented generation (RAG)

Miscellaneous

# Reference architectures Source: https://docs.pinecone.io/examples/reference-architectures Official AWS reference architecture for building high-scale production systems with Pinecone, including Pulumi IaC, documentation, and video tutorial.
The official AWS Reference Architecture for high-scale systems using Pinecone.
[Documentation](https://github.com/pinecone-io/aws-reference-architecture-pulumi/blob/main/README.md) [Video tutorial](https://youtu.be/ySznARngHts) [Source code](https://github.com/pinecone-io/aws-reference-architecture-pulumi) # Sample apps Source: https://docs.pinecone.io/examples/sample-apps Full-stack sample applications built with Pinecone: semantic search over PDFs, multi-tenant RAG with namespace isolation, multimodal search, and Assistant chat.

More code examples

# Agent Skills Source: https://docs.pinecone.io/integrations/agent-skills Install the Pinecone Agent Skills library in any agentic IDE to manage indexes, run semantic search, and build RAG assistants with natural language. Pinecone's official [Agent Skills](https://github.com/pinecone-io/skills) library brings Pinecone capabilities to any agentic IDE that supports the Agent Skills standard. Use skills to manage indexes, run semantic search, create document Q\&A assistants, and more — all through natural language in your IDE. Compatible with [GitHub Copilot](https://github.com/features/copilot), [Codex](https://chatgpt.com/codex), and other agentic IDEs. If you use **Claude Code**, install the dedicated [Pinecone plugin for Claude Code](/integrations/claude-code) instead. If you use **Gemini CLI**, install the dedicated [Pinecone extension for Gemini CLI](/integrations/gemini-cli) instead. If you use **Cursor**, install the dedicated [Pinecone plugin for Cursor](/integrations/cursor) instead. Each includes additional features specific to that tool. ## Features * **Built-in skills** for index management, semantic search, full-text search, assistant creation, and more * **Universal compatibility** with any IDE that supports Agent Skills * **Works with the Pinecone MCP server** for direct index operations ## Prerequisites * A [Pinecone API key](https://app.pinecone.io/organizations/-/keys) * [Node.js](https://nodejs.org/) installed (for `npx`) * [Pinecone MCP server](/guides/operations/mcp-server) configured in your IDE (optional, enables the `query` skill) * [uv](https://docs.astral.sh/uv/getting-started/installation/) installed (optional, runs bundled Python scripts) * [Pinecone CLI](/reference/cli/quickstart) installed (optional, enables the `cli` skill) ## Installation ```shell theme={null} export PINECONE_API_KEY="YOUR_API_KEY" ``` Replace `YOUR_API_KEY` with your [Pinecone API key](https://app.pinecone.io/organizations/-/keys). ```shell theme={null} npx skills add pinecone-io/skills ``` This downloads Pinecone's skills into your project, making them available to your IDE's AI agent. For full functionality, configure the [Pinecone MCP server](/guides/operations/mcp-server) in your IDE. This enables the `query` skill and direct index operations. ## Available skills | Skill | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **quickstart** | Step-by-step onboarding — create an index, upload data, and run your first search. | | **query** | Search integrated indexes using natural language text via the Pinecone MCP. | | **assistant** | Create, manage, and chat with Pinecone Assistants for document Q\&A with citations. | | **cli** | Use the Pinecone CLI for terminal-based index and vector management across all index types. | | **full-text-search** | Create, ingest into, and query a Pinecone full-text-search (FTS) index using the preview API. | | **n8n** | Build [n8n](/integrations/n8n) workflows with the Pinecone Assistant node or Pinecone Vector Store, including best practices and full workflow JSON generation. | | **mcp** | Reference for all available Pinecone MCP server tools and their parameters. | | **pinecone-docs** | Curated links to official Pinecone documentation, organized by topic. | | **help** | Overview of all skills and what you need to get started. | ## MCP tools Agent Skills work alongside the [Pinecone MCP server](/guides/operations/mcp-server), which provides tools for listing indexes, creating indexes, upserting records, searching, reranking, and more. Configure the MCP server in your IDE to enable the `query` skill and direct index operations. For the full list of MCP tools, see [Use the Pinecone MCP server](/guides/operations/mcp-server). ## Resources * [GitHub repository](https://github.com/pinecone-io/skills) * [Pinecone MCP server guide](/guides/operations/mcp-server) # Airbyte Source: https://docs.pinecone.io/integrations/airbyte Use the Airbyte Pinecone destination connector to build no-code ETL pipelines that embed source data and upsert vectors for semantic search and RAG. Airbyte offers a platform for creating ETL pipelines without writing integration code. It supports integrations with hundreds of systems, including databases, data warehouses, and SaaS products. The Pinecone connector for Airbyte allows users to connect these systems directly into Pinecone. The connector fetches data from the connected source, embeds the data using an large language model (LLM), and then upserts it into Pinecone. From enhancing semantic search capabilities to building intelligent recommendation systems, the Pinecone Airbyte connector offers a versatile solution. By tapping into Airbyte's extensive array of source connectors, you can explore new ways to enrich your data-driven projects and achieve your specific goals. ## Related articles * [Data Sync and Search: Pinecone and Airbyte](https://www.pinecone.io/learn/series/airbyte/) * [Introduction to Airbyte and the Pinecone connector](https://www.pinecone.io/learn/series/airbyte/airbyte-and-pinecone-intro/) * [Postgres to Pinecone Syncing](https://www.pinecone.io/learn/series/airbyte/airbyte-postgres-to-pinecone/) # Apify Source: https://docs.pinecone.io/integrations/apify Use the Apify Pinecone integration to crawl and scrape websites, embed the results, and upsert vectors for RAG and semantic search over web content. [Apify](https://apify.com) is a web scraping and data extraction platform. It provides an app store with more than a thousand ready-made cloud tools called Actors. These tools are suitable for use cases including extracting structured data from e-commerce sites, social media, search engines, online maps, or any other website. For example, the [Website Content Crawler](https://apify.com/apify/website-content-crawler) Actor can deeply crawl websites, clean their HTML by removing a cookies modal, footer, or navigation, and then transform the HTML into Markdown. This Markdown can then be used as training data for AI models or to feed LLM and generative AI applications with web content. The Apify integration for Pinecone makes it easy to transfer results from Actors to the Pinecone vector database, enabling Retrieval-Augmented Generation (RAG) or semantic search over data extracted from the web. # Aryn Source: https://docs.pinecone.io/integrations/aryn Use Aryn Sycamore and the Partitioning Service with Pinecone to extract, chunk, and embed complex PDFs and documents for higher-accuracy RAG pipelines. Aryn is an AI-powered ETL system for complex, unstructured documents like PDFs, HTML, presentations, and more. It's purpose-built for building RAG and GenAI applications, providing up to 6x better accuracy in chunking and extracting information from documents. This can lead to 30% better recall and 2x improvement in answer accuracy for real-world use cases. Aryn's ETL system has two components: Sycamore and the Aryn Partitioning Service. Sycamore is Aryn's open source document processing engine, available as a Python library. It contains a set of transforms for information extraction, LLM-powered enrichment, data cleaning, creating vector embeddings, and loading Pinecone indexes. The Aryn Partitioning Service is used as a first step in a Sycamore data processing pipeline, and it identifies and extracts parts of documents, like text, tables, images, and more. It uses a state-of-the-art vision segmentation AI model, trained on hundreds of thousands of human-annotated documents. The Pinecone integration with Aryn enables developers to easily chunk documents, create vector embeddings, and load Pinecone with high-quality data. # Box Source: https://docs.pinecone.io/integrations/box Connect Box folders to Pinecone Database to embed documents with Pinecone Inference and build RAG agents and semantic search over Box content. Connect a [Box](https://www.box.com/) account to a Pinecone vector database. This integration allows embeddings generation based on content stored in a particular account and folder in Box. By default, the Pinecone Inference API is used, as well as OpenAI for the LLM. The integration can be used within a larger AI agent or workflow. # Claude Code Plugin Source: https://docs.pinecone.io/integrations/claude-code Install the official Pinecone plugin for Claude Code to manage indexes, run vector search, and build RAG assistants from the terminal with slash commands. The official Pinecone plugin for [Claude Code](https://claude.ai/code) provides AI-powered skills, MCP server integration, and slash commands directly in your terminal. Use natural language to manage indexes, query data, build RAG applications, and create document Q\&A assistants — all with up-to-date Pinecone API knowledge. ## Features * **Built-in skills** for index management, semantic search, full-text search, assistant creation, and more * **MCP server integration** for direct Pinecone operations from Claude Code * **Slash commands** like `/pinecone:quickstart` and `/pinecone:query` for quick access * **Natural language recognition** — assistant commands work without explicit slash commands ## Prerequisites * A [Pinecone API key](https://app.pinecone.io/organizations/-/keys) * [Node.js](https://nodejs.org/) installed (`npx` must be on your `PATH`) * [uv](https://docs.astral.sh/uv/getting-started/installation/) installed (required for assistant commands) * [Pinecone CLI](/reference/cli/quickstart) installed (optional, for advanced operations) ## Installation ```shell theme={null} export PINECONE_API_KEY="YOUR_API_KEY" ``` Replace `YOUR_API_KEY` with your [Pinecone API key](https://app.pinecone.io/organizations/-/keys). From your terminal: ```shell theme={null} claude plugin install pinecone ``` Or from within Claude Code: ```text theme={null} /plugin install pinecone ``` Restart Claude Code to activate the plugin. Then run `/pinecone:help` to verify the installation. ## Available skills | Skill | Command | Description | | -------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Help** | `/pinecone:help` | Overview of all skills and setup requirements. | | **Quickstart** | `/pinecone:quickstart` | Interactive onboarding — create an index, upsert data, and query. | | **Query** | `/pinecone:query` | Search integrated indexes using natural language. | | **Assistant** | `/pinecone:assistant` | Create, upload, sync, and chat with Pinecone Assistants. | | **CLI** | `/pinecone:cli` | Guide for using the Pinecone CLI from the terminal. | | **Full-text search** | `/pinecone:full-text-search` | Create, ingest into, and query a Pinecone full-text-search (FTS) index using the preview API. | | **n8n** | `/pinecone:n8n` | Build [n8n](/integrations/n8n) workflows with the Pinecone Assistant node or Pinecone Vector Store, including best practices and full workflow JSON generation. | | **MCP** | `/pinecone:mcp` | Reference for all Pinecone MCP server tools. | | **Docs** | `/pinecone:docs` | Curated links to official Pinecone documentation. | ## MCP tools The plugin includes the Pinecone MCP server, which provides the following tools: * `search-docs` — Search the official Pinecone documentation. * `list-indexes` — List all available Pinecone indexes. * `describe-index` — Get index configuration and namespaces. * `describe-index-stats` — Get record counts and namespace statistics. * `create-index-for-model` — Create a new index with integrated embeddings. * `upsert-records` — Insert or update records in an index. * `search-records` — Search records with optional metadata filtering and reranking. * `cascading-search` — Search across multiple indexes with deduplication and reranking. * `rerank-documents` — Rerank documents using a specified reranking model. For full MCP server documentation, see [Use the Pinecone MCP server](/guides/operations/mcp-server). ## Resources * [GitHub repository](https://github.com/pinecone-io/pinecone-claude-code-plugin) * [Pinecone MCP server guide](/guides/operations/mcp-server) * [Claude Code documentation](https://docs.claude.com/en/docs/claude-code/quickstart) # Confluent Source: https://docs.pinecone.io/integrations/confluent Use the Pinecone Sink Connector for Confluent Kafka to stream events, embed them with LLMs, and upsert vectors for real-time semantic search and RAG. Confluent allows you to connect and process all of your data in real time with a cloud-native and complete data streaming platform available everywhere you need it. Confluent's Kafka Connect is a tool for scalably and reliably streaming data between Apache Kafka and other data systems. It makes it simple to quickly define connectors that move large data sets in and out of Kafka. Use the Pinecone Sink Connector, a Kafka Connect plugin for Pinecone, to take content from Confluent Cloud, convert it into vector embeddings using large language models (LLMs), and then store these embeddings in a Pinecone vector database. # Cursor Plugin Source: https://docs.pinecone.io/integrations/cursor Install the official Pinecone plugin for Cursor to manage indexes, run vector search, and build RAG apps from the editor using MCP and slash commands. The official Pinecone plugin for [Cursor](https://www.cursor.com/) provides AI-powered skills, MCP server integration, and slash commands directly in your editor. Use natural language to manage indexes, query data, build RAG applications, and create document Q\&A assistants — all with up-to-date Pinecone API knowledge. ## Features * **Built-in skills** for index management, semantic search, full-text search, assistant creation, and more * **Bundled MCP server** (`@pinecone-database/mcp`) for direct Pinecone operations from Cursor Agent * **Slash commands** like `/pinecone-quickstart` and `/pinecone-query` for quick access * **Natural language activation** — Cursor Agent invokes the right skill automatically based on your conversation ## Prerequisites * A [Pinecone API key](https://app.pinecone.io/organizations/-/keys) * [Cursor](https://www.cursor.com/) installed * [Node.js](https://nodejs.org/) v18+ (required for the bundled MCP server) * [uv](https://docs.astral.sh/uv/getting-started/installation/) installed (optional, runs bundled Python scripts) * [Pinecone CLI](/reference/cli/quickstart) installed (optional, enables the `pinecone-cli` skill) ## Installation Add your [Pinecone API key](https://app.pinecone.io/organizations/-/keys) to a `.env` file at your workspace root: ```text theme={null} PINECONE_API_KEY=your-key ``` Cursor loads this file into the MCP server via its [`envFile`](https://cursor.com/docs/mcp) field, so you don't need to export the key in your shell. In Cursor chat, run: ```text theme={null} /add-plugin pinecone ``` Or install directly from the [Cursor Marketplace](https://cursor.com/marketplace/pinecone). Open Cursor Agent chat and run `/pinecone-help` to confirm the skills are loaded. You can also check: * **Skills:** Cursor Settings > Rules — listed under "Agent Decides" * **MCP server:** Cursor Settings > Features > Model Context Protocol ## Available skills | Skill | Command | Description | | -------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Help** | `/pinecone-help` | Overview of all skills and setup requirements. | | **Quickstart** | `/pinecone-quickstart` | Interactive onboarding — create an index, upsert data, and query. Choose between a Database path or Assistant path. | | **Query** | `/pinecone-query` | Search integrated indexes using natural language via the Pinecone MCP server. | | **Assistant** | `/pinecone-assistant` | Create, upload, sync, and chat with Pinecone Assistants for document Q\&A with citations. | | **CLI** | `/pinecone-cli` | Guide for using the Pinecone CLI (`pc`) from the terminal. | | **Full-text search** | `/pinecone-full-text-search` | Create, ingest into, and query a Pinecone full-text-search (FTS) index using the preview API. | | **n8n** | `/pinecone-n8n` | Build [n8n](/integrations/n8n) workflows with the Pinecone Assistant node or Pinecone Vector Store, including best practices and full workflow JSON generation. | | **MCP** | `/pinecone-mcp` | Reference for all Pinecone MCP server tools. | | **Docs** | `/pinecone-docs` | Curated links to official Pinecone documentation. | ## MCP tools The plugin includes the Pinecone MCP server, which provides the following tools: * `search-docs` — Search the official Pinecone documentation. * `list-indexes` — List all available Pinecone indexes. * `describe-index` — Get index configuration and namespaces. * `describe-index-stats` — Get record counts and namespace statistics. * `create-index-for-model` — Create a new index with integrated embeddings. * `upsert-records` — Insert or update records in an index. * `search-records` — Search records with optional metadata filtering and reranking. * `cascading-search` — Search across multiple indexes with deduplication and reranking. * `rerank-documents` — Rerank documents using a specified reranking model. For full MCP server documentation, see [Use the Pinecone MCP server](/guides/operations/mcp-server). ## Resources * [GitHub repository](https://github.com/pinecone-io/pinecone-cursor-plugin) * [Cursor Marketplace listing](https://cursor.com/marketplace/pinecone) * [Pinecone MCP server guide](/guides/operations/mcp-server) * [Cursor documentation](https://cursor.com/docs) # Databricks Source: https://docs.pinecone.io/integrations/databricks Use Databricks and the Pinecone Spark connector to distribute embedding jobs across a cluster and upsert vectors at scale for semantic search and RAG. Databricks is a Unified Analytics Platform on top of Apache Spark. The primary advantage of using Spark is its ability to distribute workloads across a cluster of machines. By adding more machines or increasing the number of cores on each machine, it is easy to horizontally scale a cluster to handle computationally intensive tasks like vector embedding, where parallelization can save many hours of precious computation time and resources. Leveraging GPUs with Spark can produce even better results — enjoying the benefits of the fast computation of a GPU combined with parallelization will ensure optimal performance. Efficiently create, ingest, and update vector embeddings at scale with Databricks and Pinecone. ## Setup guide In this guide, you'll create embeddings based on the [sentence-transformers/all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2) model from [Hugging Face](https://huggingface.co/), but the approach demonstrated here should work with any other model and dataset. ### Before you begin Ensure you have the following: * A [Databricks cluster](https://docs.databricks.com/en/compute/configure.html) * A [Pinecone account](https://app.pinecone.io/) * A [Pinecone API key](/guides/projects/understanding-projects#api-keys) ### 1. Install the Spark-Pinecone connector 1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster). 2. Configure the library as follows: 1. Select **File path/S3** as the **Library Source**. 2. Enter the S3 URI for the Pinecone assembly JAR file: ``` s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar ``` Databricks platform users must use the Pinecone assembly jar listed above to ensure that the proper dependecies are installed. 3. Click **Install**. 1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster). 2. Configure the library as follows: 1. Select **File path/S3** as the **Library Source**. 2. Enter the S3 URI for the Pinecone assembly JAR file: ``` s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar ``` 3. Click **Install**. 1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster). 2. Configure the library as follows: 1. [Download the Pinecone assembly JAR file](https://repo1.maven.org/maven2/io/pinecone/spark-pinecone_2.12/1.1.0/). 2. Select **Workspace** as the **Library Source**. 3. Upload the JAR file. 4. Click **Install**. ### 2. Load the dataset into partitions As your example dataset, use a collection of news articles from Hugging Face's datasets library: 1. [Create a new notebook](https://docs.databricks.com/en/notebooks/notebooks-manage.html#create-a-notebook) attached to your cluster. 2. Install dependencies: ``` pip install datasets transformers pinecone torch ``` 3. Load the dataset: ```Python Python theme={null} from datasets import list_datasets, load_dataset dataset_name = "allenai/multinews_sparse_max" dataset = load_dataset(dataset_name, split="train") ``` 4. Convert the dataset from the Hugging Face format and repartition it: ```Python Python theme={null} dataset.to_parquet("/dbfs/tmp/dataset_parquet.pq") num_workers = 10 dataset_df = spark.read.parquet("/tmp/dataset_parquet.pq").repartition(num_workers) ``` Once the repartition is complete, you get back a DataFrame, which is a distributed collection of the data organized into named columns. It is conceptually equivalent to a table in a relational database or a dataframe in R/Python, but with richer optimizations under the hood. As mentioned above, each partition in the dataframe has an equal amount of the original data. 5. The dataset doesn't have identifiers associated with each document, so add them: ```Python Python theme={null} from pyspark.sql.types import StringType from pyspark.sql.functions import monotonically_increasing_id dataset_df = dataset_df.withColumn("id", monotonically_increasing_id().cast(StringType())) ``` As its name suggests, `withColumn` adds a column to the dataframe, containing a simple increasing identifier that you cast to a string. ### 3. Create the vector embeddings 1. Create a UDF (User-Defined Function) to create the embeddings, using the AutoTokenizer and AutoModel classes from the Hugging Face transformers library: ```Python Python theme={null} from transformers import AutoTokenizer, AutoModel def create_embeddings(partitionData): tokenizer = AutoTokenizer.from_pretrained("sentence-transformers/all-MiniLM-L6-v2") model = AutoModel.from_pretrained("sentence-transformers/all-MiniLM-L6-v2") for row in partitionData: document = str(row.document) inputs = tokenizer(document, padding=True, truncation=True, return_tensors="pt", max_length=512) result = model(**inputs) embeddings = result.last_hidden_state[:, 0, :].cpu().detach().numpy() lst = embeddings.flatten().tolist() yield [row.id, lst, "", "{}", None] ``` 2. Apply the UDF to the data: ```Python Python theme={null} embeddings = dataset_df.rdd.mapPartitions(create_embeddings) ``` A dataframe in Spark is a higher-level abstraction built on top of a more fundamental building block called a resilient distributed dataset (RDD). Here, you use the `mapPartitions` function, which provides finer control over the execution of the UDF by explicitly applying it to each partition of the RDD. 3. Convert the resulting RDD back into a dataframe with the schema required by Pinecone: ```Python Python theme={null} from pyspark.sql.types import StructType, StructField, StringType, ArrayType, FloatType, IntegerType schema = StructType([ StructField("id",StringType(),True), StructField("values",ArrayType(FloatType()),True), StructField("namespace",StringType(),True), StructField("metadata", StringType(), True), StructField("sparse_values", StructType([ StructField("indices", ArrayType(LongType(), False), False), StructField("values", ArrayType(FloatType(), False), False) ]), True) ]) embeddings_df = spark.createDataFrame(data=embeddings,schema=schema) ``` ### 4. Save the embeddings in Pinecone 1. Initialize the connection to Pinecone: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key="YOUR_API_KEY") ``` 2. Create an index for your embeddings: ```Python Python theme={null} pc.create_index( name="news", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ) ) ``` 3. Use the Spark-Pinecone connector to save the embeddings to your index: ```Python Python theme={null} ( embeddings_df.write .option("pinecone.apiKey", api_key) .option("pinecone.indexName", index_name) .format("io.pinecone.spark.pinecone.Pinecone") .mode("append") .save() ) ``` The process of writing the embeddings to Pinecone should take approximately 15 seconds. When it completes, you'll see the following: ``` spark: org.apache.spark.sql.SparkSession = org.apache.spark.sql.SparkSession@41638051 pineconeOptions: scala.collection.immutable.Map[String,String] = Map(pinecone.apiKey ->, pinecone.indexName -> "news") ``` This means the process was completed successfully and the embeddings have been stored in Pinecone. 4. Perform a similarity search using the embeddings you loaded into Pinecone by providing a set of vector values or a vector ID. The [query endpoint](/reference/api/2025-10/data-plane/query) will return the IDs of the most similar records in the index, along with their similarity scores: ```Python Python theme={null} index.query( namespace="example-namespace", vector=[0.3, 0.3, 0.3, 0.3, 0.3], top_k=3, include_values=True ) ``` If you want to make a query with a text string (e.g., `"Summarize this article"`), use the [`search` endpoint via integrated inference](/reference/api/2025-10/data-plane/search_records). # Datavolo Source: https://docs.pinecone.io/integrations/datavolo Use Datavolo pipelines to source, transform, and enrich unstructured data into Pinecone for retrieval augmented generation and multimodal AI apps. [Datavolo](https://datavolo.io/) helps data teams build multimodal data pipelines to support their AI initiatives. Every organization has their own private data that they need to incorporate into their AI apps, and a predominant pattern to do so has emerged: retrieval augmented generation (RAG). Datavolo sources, transforms, and enriches data in a continuous, composable and customizable manner, landing the data in Pinecone for retrieval. This ensures organizations can securely access their unstructured data. # Estuary Source: https://docs.pinecone.io/integrations/estuary Use the Estuary Pinecone connector to build real-time, millisecond-latency pipelines that incrementally embed source data for LLM search and RAG. [Estuary](https://estuary.dev/) builds real-time data pipelines that focus on moving data from sources to destinations with millisecond latency. It supports integrations with hundreds of systems including databases, warehouses, SaaS products and streaming solutions. The Pinecone connector for Estuary enables users to source from these systems and push data to Pinecone, for an always up-to-date view. It incrementally updates source data to ensure that minimal credits are used when reaching out to get embeddings from providers prior to pushing them to Pinecone. Estuary's Pinecone connector enables a variety of use cases like enabling LLM-based search across your organizations data and building intelligent recommendation systems. It can be set up in 5 minutes, without any engineering effort to maximize efficiency. # Fleak Source: https://docs.pinecone.io/integrations/fleak Use Fleak's low-code workflows with Pinecone to combine SQL, LLM inference, and vector search in serverless APIs for RAG and data enrichment pipelines. Fleak simplifies the process of building, deploying, and managing data workflows. As a low-code platform, Fleak lets users create and deploy complex workflows using SQL and pre-configured processing nodes. The platform facilitates seamless data processing, microservice interactions, and the inference of large language models (LLMs) within a single, intuitive environment. Fleak makes advanced technology accessible and manageable for Pinecone users without requiring extensive coding hours or infrastructure knowledge. The platform provides serverless, autoscaling HTTP API endpoints, ensuring that workflows are robust, reliable, and scalable to meet the complex data needs of enterprises. This setup allows businesses to automate and enhance their operations, driving productivity and innovation through powerful, user-friendly tools. By integrating Pinecone into Fleak's platform, users can access and leverage their vector data to enrich their workflows without additional engineering overhead, enabling seamless data-driven decision-making, advanced analytics, and the integration of AI-driven insights. # FlowiseAI Source: https://docs.pinecone.io/integrations/flowise Use FlowiseAI with Pinecone to build low-code LLM apps that upsert documents and query vector indexes for RAG chatbots and semantic search flows. Flowise is a low-code LLM apps development platform. It supports integrations with dozens of systems, including databases and chat models. The Pinecone integration with Flowise allows users to build RAG apps, including upserting and querying documents. # Gathr Source: https://docs.pinecone.io/integrations/gathr Use Gathr's no-code data-to-outcome platform with Pinecone to build enterprise RAG apps, chatbots, and vector pipelines from ingestion through deployment. [Gathr](https://www.gathr.one/) is the world's first and only "data to outcome" platform. Leading enterprises use Gathr to build and operationalize data and AI-driven solutions at scale. Gathr unifies data engineering, machine learning, generative AI, actionable analytics, and process automation on a single platform. With Gen AI capabilities and no-code rapid application development, Gathr significantly boosts productivity for all. The unified experience fosters seamless handoff and collaboration between teams, accelerating the journey from prototype to production. Users have achieved success with Gathr, from ingesting petabyte-scale data in real time to orchestrating thousands of complex data processing pipelines in months and delivering actionable insights and xOps solutions to multiply business impact. Additionally, Gathr helps enterprises architect Gen AI solutions for use cases like document summarization, sentiment analysis, next best action, insider threat detection, predictive maintenance, custom chatbots, and more. Gathr Gen AI Fabric is designed to build enterprise-grade Gen AI solutions end-to-end on a unified platform. It offers production-ready building blocks for creating Gen AI solutions, out-of-the-box Gen AI solution templates, and GathrIQ, a data-to-outcome copilot. One of the building blocks is integration with Vector DB and Knowledge Graphs. Gathr supports reading and writing from Pinecone using a built-in, ready-to-use connector to support use cases requiring knowledge graphs. # Gemini CLI Extension Source: https://docs.pinecone.io/integrations/gemini-cli Install the official Pinecone extension for Gemini CLI to manage indexes, run vector search, and build RAG assistants with natural-language commands. The official Pinecone extension for [Gemini CLI](https://github.com/google-gemini/gemini-cli) provides AI-powered skills and MCP server integration directly in your terminal. Use natural language to manage indexes, query data, build RAG applications, and create document Q\&A assistants. ## Features * **7 built-in skills** for index management, semantic search, assistant creation, and more * **MCP server integration** for direct Pinecone operations from Gemini CLI * **Natural language activation** — just describe what you want and the right skill is invoked automatically ## Prerequisites * A [Pinecone API key](https://app.pinecone.io/organizations/-/keys) * [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed * [uv](https://docs.astral.sh/uv/getting-started/installation/) installed (required for skill scripts) * [Pinecone CLI](/reference/cli/quickstart) installed (optional, for advanced operations) ## Installation ```shell theme={null} export PINECONE_API_KEY="YOUR_API_KEY" ``` Replace `YOUR_API_KEY` with your [Pinecone API key](https://app.pinecone.io/organizations/-/keys). ```shell theme={null} gemini extensions install https://github.com/pinecone-io/gemini-cli-extension ``` Restart Gemini CLI to activate the extension. Then ask: ```text theme={null} Use the help skill to show me what Pinecone skills are available. ``` If you hit API key errors, exit Gemini CLI, run `export PINECONE_API_KEY="your-key"` in your terminal, and start Gemini CLI again. The CLI only reads environment variables at launch. ## Available skills | Skill | Description | | ----------------- | ----------------------------------------------------------------------------------- | | **quickstart** | Step-by-step onboarding — create an index, upload data, and run your first search. | | **query** | Search integrated indexes using natural language text via the Pinecone MCP. | | **assistant** | Create, manage, and chat with Pinecone Assistants for document Q\&A with citations. | | **cli** | Guide for using the Pinecone CLI from the terminal. | | **mcp** | Reference for all available Pinecone MCP server tools and their parameters. | | **pinecone-docs** | Curated links to official Pinecone documentation, organized by topic. | | **help** | Overview of all skills and what you need to get started. | Skills are activated automatically based on your conversation. If the agent doesn't pick up a specific skill, explicitly ask for it: *"Use the quickstart skill to help me get started."* ## MCP tools The extension includes the Pinecone MCP server, which provides the following tools: * `search-docs` — Search the official Pinecone documentation. * `list-indexes` — List all available Pinecone indexes. * `describe-index` — Get index configuration and namespaces. * `describe-index-stats` — Get record counts and namespace statistics. * `create-index-for-model` — Create a new index with integrated embeddings. * `upsert-records` — Insert or update records in an index. * `search-records` — Search records with optional metadata filtering and reranking. * `cascading-search` — Search across multiple indexes with deduplication and reranking. * `rerank-documents` — Rerank documents using a specified reranking model. For full MCP server documentation, see [Use the Pinecone MCP server](/guides/operations/mcp-server). ## Resources * [GitHub repository](https://github.com/pinecone-io/gemini-cli-extension) * [Pinecone MCP server guide](/guides/operations/mcp-server) * [Gemini CLI documentation](https://github.com/google-gemini/gemini-cli) # Integrations Source: https://docs.pinecone.io/integrations/overview Browse Pinecone integrations across vector embedding providers, data ingestion tools, frameworks, and infrastructure to ship AI apps faster. IDEs & CLIs

Agent Skills

Universal Pinecone skills library for GitHub Copilot, Codex, and other agentic IDEs.

 IDEs & CLIs

Cursor Plugin

Official Pinecone plugin for Cursor with skills, MCP tools, and slash commands.
Frameworks

AI Engine

Create intelligent chatbots, generate content, build AI forms, and automate tasks — all from your WordPress dashboard.
Data Sources

Airbyte

Seamlessly integrate, transform, and load data into Pinecone from hundreds of systems, including databases, data warehouses, and SaasS products.
Frameworks

Amazon Bedrock

Integrate your enterprise data into Amazon Bedrock using Pinecone to build highly performant GenAI applications.
Frameworks

Amazon Sagemaker

Integrate machine learning models seamlessly with a fully-managed service that enables easy deployment and scalability.
Models

Anyscale

Focus on building applications powered by LLMs without the need to worry about the underlying infrastructure.
Data Sources

Apify

Integrate results from web scrapers or crawlers into a vector database to support RAG or semantic search over web content.
Data Sources

Aryn

Process complex, unstructured documents with a purpose-built ETL system for RAG and GenAI applications.
Infrastructure

AWS Marketplace

Access Pinecone through our AWS Marketplace listing.
Data Sources

Box

Connect a Box account to a Pinecone vector database.

 IDEs & CLIs

Claude Code Plugin

Official Pinecone plugin for Claude Code with skills, MCP tools, and slash commands.
Frameworks

Cloudera AI

Vector embedding, RAG, and semantic search at scale.
Models

Cohere

Leverage cutting-edge natural language processing tools for enhanced text understanding and generation in your applications.
Data Sources

Confluent

Connect and process all of your data in real time with a cloud-native and complete data streaming platform.
Frameworks

Context Data

Create end-to-end data flows that connect data sources to Pinecone.
Data Sources

Databricks

Combine the power of a unified analytics platform with Pinecone for scalable data processing and AI insights.
Observability

Datadog

Monitor and secure your applications by integrating with a cloud-scale monitoring service that provides real-time analytics.
Data Sources

Datavolo

Source, transform, and enrich data in a continuous, composable and customizable manner.
Data Sources

Estuary

Source data from hundreds systems and push data to Pinecone, for an always up-to-date view.
Data Sources

FlowiseAI

Build customized LLM apps with an open source, low-code tool for developing orchestration flow & AI agents.
Data Sources

Fleak

Build, deploy, and manage complex workflows with a low-code platform for AI-assisted ML and LLM transformations.
Data Sources

Gathr

Build and operationalize data and AI-driven solutions at scale.
Infrastructure

Google Cloud Marketplace

Access Pinecone through our Google Cloud Marketplace listing.

 IDEs & CLIs

Gemini CLI Extension

Official Pinecone extension for Gemini CLI with skills and MCP tools.
Frameworks

Genkit

Build AI powered applications and agents.
IDEs & CLIs

GitHub Copilot

Get personalized recommendations that enable you to retrieve relevant data and collaborate effectively with Copilot.
Frameworks

Haystack

Implement an end-to-end search pipeline for efficient retrieval and question answering over large datasets.
Observability

HoneyHive

Clearly visualize your execution traces and spans.
Frameworks

Hugging Face

Deploy state-of-the-art machine learning models on scalable infrastructure, streamlining the path from prototype to production.
Frameworks

Instill AI

Streamline AI development with a low-code full-stack infrastructure tool for data, model, and pipeline orchestration.
Models

Jina

Leverage powerful AI models to generate high-quality text embeddings, fine-tuned to both domain- and language-specific use cases.
Frameworks

LangChain

Combine language models with chain-of-thought reasoning for advanced problem solving and decision support.
Observability

Langtrace

Access rich and high cardinal tracing for Pinecone API calls, ingestible into your observability tool of choice.
Frameworks

Llama Index

Leverage Llama for indexing and retrieving information at scale, improving data access and analysis.
Data Sources

Matillion

Easily create and maintain data pipelines, build custom connectors for any source, and enjoy AI and high-code options to suit any need.
Infrastructure

Microsoft Marketplace

Access Pinecone through our Microsoft Marketplace listing.
n8n
Frameworks

n8n

Build AI workflows with the Pinecone Assistant or Vector Store node—managed RAG or full control over your pipeline.
Observability

New Relic

Implement monitoring and integrate your Pinecone application with New Relic for performance analysis and insights.
Data Sources

Nexla

Ingest data from 500+ connectors with Nexla's low-code/no-code AI integration platform.
Frameworks

Nuclia

Nuclia RAG-as-a-Service automatically indexes files and documents from both internal and external sources.
Frameworks

OctoAI

Harness value from the latest AI innovations by delievering efficient, reliable, and customizable AI systems for your apps.
Models

OpenAI

Access powerful AI models like GPT for innovative applications and services, enhancing user experiences with AI capabilities.
Infrastructure

Pulumi

Manage your Pinecone collections and indexes using any language of Pulumi Infrastructure as Code.
Data Sources

Redpanda

Connect existing data sources to Pinecone with a Kafka-compatible streaming data platform built for data-intensive applications.
Data Sources

Snowflake

Run Pinecone with Snowpark Container Services, designed to deploy, manage, and scale containerized applications within the Snowflake ecosystem.
Data Sources

StreamNative

A scalable, resilient, and secure messaging and event streaming platform.
Infrastructure

Terraform

Manage your infrastructure using configuration files for a consistent workflow.
Observability

Traceloop

Produce traces and metrics that can be viewed in any OpenTelemetry-based platform.
Observability

TruLens

Gain insights into your machine learning models' decisions, improving interpretability and trustworthiness.
Models

Twelve Labs

Create high-quality multimodal embeddings that capture the rich context and interactions between different modalities in videos.
Data Source

Unstructured

Load data into Pinecone with a single click.
Infrastructure

Vercel

Use Pinecone as the long-term memory for your Vercel AI projects, and easily scale to support billions of data points.
Frameworks

VoltAgent

A TypeScript-based, AI-agent framework for building AI applications with retrieval-augmented generation (RAG) capabilities.
Models

Voyage AI

Cutting-edge embedding models and rerankers for semantic search and RAG.
Infrastructure

Zapier

Zapier connects Pinecone to thousands of apps to help you automate your work. No code required.

 # Model Gallery Source: https://docs.pinecone.io/models/overview Browse Pinecone's hosted embedding and reranking model gallery with details on dimensions, sequence length, pricing, and supported tasks.
Inference

Build end-to-end faster with models hosted by Pinecone.

Request a model