# Build a knowledge retrieval agent Source: https://docs.pinecone.io/guides/agents/build-a-knowledge-agent Build an AI agent that uses Pinecone to retrieve knowledge and answer questions accurately, with Pinecone as a tool inside the 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. > [!NOTE] > > This guide requires an [Anthropic](https://console.anthropic.com/) or [OpenAI](https://platform.openai.com/api-keys) API key alongside your Pinecone API key. ### 1. Install dependencies ```bash Anthropic (Claude) theme={null} pip install --upgrade pinecone anthropic ``` ```bash OpenAI theme={null} pip install --upgrade pinecone openai ``` ### 2. Create an index and load knowledge Create a document index whose `content` field uses [integrated embedding](/guides/search/integrated-embedding), so Pinecone embeds the text for you, 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, SchemaBuilder pc = Pinecone(api_key="{{YOUR_API_KEY}}") llm = anthropic.Anthropic(api_key="YOUR_ANTHROPIC_API_KEY") # Create a document index that embeds the content field if not pc.indexes.exists(name="knowledge"): pc.indexes.create( name="knowledge", schema=( SchemaBuilder() .add_string_field(name="content", embed={"model": "llama-text-embed-v2"}) .build() ), ) index = pc.index(name="knowledge") # Load your knowledge base index.documents.upsert( namespace="docs", documents=[ {"_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, SchemaBuilder pc = Pinecone(api_key="{{YOUR_API_KEY}}") llm = OpenAI(api_key="YOUR_OPENAI_API_KEY") # Create a document index that embeds the content field if not pc.indexes.exists(name="knowledge"): pc.indexes.create( name="knowledge", schema=( SchemaBuilder() .add_string_field(name="content", embed={"model": "llama-text-embed-v2"}) .build() ), ) index = pc.index(name="knowledge") # Load your knowledge base index.documents.upsert( namespace="docs", documents=[ {"_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"}, ], ) ``` > [!NOTE] > > Pinecone is eventually consistent. New documents may take a few seconds to become searchable. ### 3. Define Pinecone as a tool 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.documents.search( namespace="docs", top_k=3, score_by=[{"type": "embed", "fields": ["content"], "query": query}], # To scope by metadata, add filter={"category": {"$eq": "policies"}} include_fields=["content"], ) return "\n\n".join(match.content for match in results.matches) ``` ### 4. Wire the tool into your agent 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-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-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 ``` ### 5. Ask your agent a question ```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 documents 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?")) ``` > [!NOTE] > > **What just happened:** Your LLM received a question, decided it needed more information, and called the `search_knowledge_base` tool. Pinecone embedded the query and returned the most relevant documents, 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 > [card] [Use the MCP server](/guides/agents/mcp-server) > > Give agents Pinecone access over the Model Context Protocol > [card] [Search methods](/guides/search/search-overview) > > Compare full-text, semantic, sparse-vector, and hybrid search > [card] [Data modeling](/guides/indexes/data-modeling) > > Model your data for efficient retrieval # Use the Pinecone MCP server Source: https://docs.pinecone.io/guides/agents/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. > [!NOTE] > > 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). > [!TIP] > > Pinecone also offers plugins with built-in skills for AI coding tools. See [AI coding tools](/integrations/ai-coding-tools) for an overview. You can also go straight to the [Claude Code plugin](/integrations/claude-code), [Codex plugin](/integrations/codex), [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 legacy integrated index that uses a hosted embedding model to embed text as vectors. * `upsert-records`: Inserts or updates records in a legacy integrated index. * `search-records`: Searches for records in a legacy integrated index based on a text query. 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. > [!NOTE] > > The Pinecone MCP supports only [indexes with integrated embedding](/guides/indexes/index-data-overview#vector-embedding). Indexes for vectors you create with external embedding models aren't 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. **1. Add the MCP server** **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). **2. Check the status** 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. **3. Test the server** 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 > [!TIP] > > 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. **1. Add 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"}}' ``` **2. Check the status** 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 ``` **3. Test the server** 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 **1. Add the MCP server** 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. **2. Check the status** Restart Claude Desktop. On the new chat screen, you should see a hammer (MCP) icon appear with the new MCP tools available. **3. Test the server** 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 > [!TIP] > > 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. **1. Add 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}}" } } } } ``` **2. Check the status** Go to **Cursor Settings > MCP**. You should see the server and its list of tools. **3. Add Pinecone rules** 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`. ``` **4. Test the server** 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. # Check usage per request Source: https://docs.pinecone.io/guides/cost/check-usage-per-request Check the read units and embedding tokens Pinecone returns on each search, fetch, list, and embedding request to see what a single call consumed. Requests that consume read units or embedding tokens return a `usage` field alongside their results. Reading it tells you what a single request cost, so you can compare approaches before running them at scale. ## Read units [Search](/guides/search/search-overview), [fetch](/guides/data/fetch-data), and [list](/guides/data/list-record-ids) requests return a `usage` field with the [read unit](/guides/cost/understand-cost#read-units) consumption of that request. > [!NOTE] > > While Pinecone tracks read unit usage with decimal precision, the Pinecone API and SDKs round these values up to the nearest whole number in search, query, fetch, and list responses. For example, if a search 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/monitor-performance) or the organization-wide [Usage dashboard](/admin/billing/download-usage-report). In the REST API and the Node.js and Go SDKs, `usage` also reports `egress_bytes` (`egressBytes` in Node.js), the size of the response that counts toward [egress](/guides/cost/understand-cost#egress). The Python SDK doesn't report `egress_bytes`, and its `documents.list` paginator doesn't expose `usage`. For example, the following search scores documents by a 1536-dimension `dense_vector` field named `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/indexes/target-an-index index = pc.index(host="INDEX_HOST") # Replace with your query embedding, which must match the index's dimension (1536 in this example) query_vector = [0.1] * 1536 response = index.documents.search( namespace="example-namespace", top_k=3, score_by=[ {"type": "dense_vector", "fields": ["embedding"], "values": query_vector} ], ) print(response.usage) ``` ```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/indexes/target-an-index const index = pc.index({ host: "INDEX_HOST", namespace: "example-namespace" }) // Replace with your query embedding, which must match the index's dimension (1536 in this example) const queryVector = new Array(1536).fill(0.1) const response = await index.documents.search({ topK: 3, scoreBy: [ { type: 'dense_vector', fields: ['embedding'], values: queryVector }, ], }) console.log(response) ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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/indexes/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) } // Replace with your query embedding, which must match the index's dimension (1536 in this example) queryVector := make([]float32, 1536) for i := range queryVector { queryVector[i] = 0.1 } res, err := idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{ TopK: 3, ScoreBy: []pinecone.DocumentScoringMethod{ {Type: pinecone.DocumentScoringTypeDenseVector, Fields: []string{"embedding"}, Values: &queryVector}, }, }) if err != nil { log.Fatalf("Failed to search documents: %v", err) } fmt.Println(prettifyStruct(res)) } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" # Replace the values with your 1536-dimension query embedding curl "https://$INDEX_HOST/namespaces/example-namespace/documents/search" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "top_k": 3, "score_by": [ { "type": "dense_vector", "fields": ["embedding"], "values": [0.1, 0.1, 0.1, ...] } ] }' ``` The response looks like this: ```python Python theme={null} DocumentSearchUsage(read_units=1, embed_total_tokens=None) ``` ```javascript JavaScript theme={null} { matches: [ { _id: 'doc4', _score: 0.8751253 }, { _id: 'doc8', _score: 0.87052643 }, { _id: 'doc1', _score: 0.8700179 } ], namespace: 'example-namespace', usage: { readUnits: 1, egressBytes: 68, embedTotalTokens: undefined } } ``` ```go Go theme={null} { "matches": [ { "_id": "doc4", "_score": 0.8751253 }, { "_id": "doc8", "_score": 0.87052643 }, { "_id": "doc1", "_score": 0.8700179 } ], "namespace": "example-namespace", "usage": { "read_units": 1, "egress_bytes": 68 } } ``` ```json curl theme={null} { "matches": [ { "_id": "doc4", "_score": 0.8751253 }, { "_id": "doc8", "_score": 0.87052643 }, { "_id": "doc1", "_score": 0.8700179 } ], "namespace": "example-namespace", "usage": { "read_units": 1, "egress_bytes": 68 } } ``` ## Embedding tokens Requests that use one of [Pinecone's hosted embedding models](/guides/indexes/index-configuration#embedding-models) return a `usage` field with the number of tokens embedded: * The [Generate vectors](/reference/api/latest/inference/generate-vectors) operation reports `total_tokens`. * Upserts and searches on an index with [integrated embedding](/guides/search/integrated-embedding) report `embed_total_tokens` (`embedTotalTokens` in Node.js). A search reports it alongside `read_units`. For example, the following request uses the `llama-text-embed-v2` model to embed sentences related to the word "apple": ```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, inputs: data.map(d => d.text), parameters: { 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/v7/pinecone" ) type Data struct { ID string 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{ "input_type": "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.Println(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: 2026-07" \ -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 response looks like this: ```python Python theme={null} EmbeddingsList(model='llama-text-embed-v2', vector_type='dense', count=6, usage=EmbedUsage(total_tokens=210)) ``` ```javascript JavaScript theme={null} { model: 'llama-text-embed-v2', vectorType: 'dense', data: [ { values: [Array], vectorType: 'dense' }, ... ], usage: { totalTokens: 210 } } ``` ```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": [ { "dense_embedding": { "vector_type": "dense", "values": [ 0.00234222412109375, -0.0709228515625, 0.052337646484375, ... ] } }, ... ], "model": "llama-text-embed-v2", "vector_type": "dense", "usage": { "total_tokens": 210 } } ``` ```json curl theme={null} { "model": "llama-text-embed-v2", "vector_type": "dense", "data": [ { "vector_type": "dense", "values": [ 0.00234222412109375, -0.0709228515625, 0.052337646484375, ... ] }, ... ], "usage": { "total_tokens": 210 } } ``` # Save on Pinecone costs Source: https://docs.pinecone.io/guides/cost/save-on-costs Lower Pinecone costs with prepaid credits and discounts, bulk import, namespaces for multitenancy, and read patterns that use fewer read units. You can lower your Pinecone bill with discounted rates and by changing how you load and read data. While you're building, the free [Starter plan](https://www.pinecone.io/pricing/) has no monthly minimum. For how usage is measured, see [Understand Pinecone cost](/guides/cost/understand-cost). ## Credits and discounts Besides changing how you use the database, you can lower the rate you pay. * Prepaid credits and annual commitments earn discounted usage rates. See [Prepaid credits](/guides/cost/understand-cost#prepaid-credits). * 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). * Standard and Enterprise customers can [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) to discuss volume discounts. ## Use bulk import for large loads To populate a new namespace or load millions of records, [import from object storage](/guides/data/import-data) instead of streaming [upserts](/guides/data/upsert-data). * Import handles one-time bulk loads from Parquet in your object store, and is priced on the data it reads during the job. See [Import cost](/guides/cost/understand-cost#imports). * Upsert is priced in write units by request size. Many small requests can cost more than a few large ones carrying the same data. See [Write unit pricing](/guides/cost/understand-cost#write-units). Use upsert (including [batch upsert](/guides/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/data/data-ingestion-overview). ## Use namespaces for multitenancy If you need to isolate each customer's or user's data, [partition tenants with namespaces](/guides/data/implement-multitenancy) instead of creating separate indexes. This often lowers storage overhead and query cost, because a query's cost depends on the size of the namespace it scans. ## Read only what you need * Avoid returning vector values from a query when you don't need them (`include_values=false`, the default), especially at high `top_k`. Values are typically the largest part of a response, so leaving them out lowers [egress](/guides/cost/understand-cost#egress) and helps you stay within your plan's egress allowance. * Where your workload allows, use [metadata filters](/guides/search/filter-by-metadata) so queries scan fewer records. * To retrieve known records without a query, use a [hierarchical ID schema](/guides/indexes/data-modeling#use-structured-ids), [list record IDs](/guides/data/list-record-ids) by prefix, and then [fetch](/guides/data/fetch-data) the records you need. A [query's read units](/guides/cost/understand-cost#query) grow with namespace size, while fetch [uses 1 read unit per 10 records](/guides/cost/understand-cost#fetch). > [!NOTE] > > Omitting values lowers egress but not [read units](/guides/cost/understand-cost#read-units). Query read unit cost depends on the size of the namespace scanned, not the size of the response. > [!NOTE] > > Indexes built on [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) aren't subject to read unit limits for query, fetch, list, and full-text search operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) guide. ## Choose the right index capacity mode For sustained, high read throughput, [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview) can be more cost-effective than on-demand when you fully use provisioned read capacity. For spiky or low-QPS workloads, on-demand may be cheaper. See [When to use dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview#when-to-use-dedicated-read-nodes) and [Understand Pinecone cost](/guides/cost/understand-cost). ## See also * [Decrease latency](/guides/optimize/decrease-latency) * [Increase throughput](/guides/optimize/increase-throughput) * [Understand Pinecone cost](/guides/cost/understand-cost) * [Check usage per request](/guides/cost/check-usage-per-request) # Set monthly spend alerts Source: https://docs.pinecone.io/guides/cost/set-spend-alerts Set monthly spend alerts in Pinecone to email the recipients you choose when your organization's spending reaches a threshold you set. You can set up email alerts that track your organization's monthly spending. An alert notifies the recipients you choose when spending reaches a threshold you set, and it resets at the start of each monthly billing cycle. > [!NOTE] > > Spend alerts are available on the [Standard and Enterprise plans](https://www.pinecone.io/pricing/). They're not needed on the Starter or Builder plans, where usage is capped by plan quotas rather than billed per unit. ## 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](/admin/organizations/organizations-overview#organization-roles) are listed by default. 5. Click **Create**. ## 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, the email addresses, or both. 3. Click **Update**. ## Auto-spend spike alert To protect against unexpected cost increases, Pinecone sends an alert when spending exceeds double your previous month's invoice. You can't change that threshold or delete the alert, but you can change which email addresses receive it and turn its notifications on or off. ## See also * [Understand Pinecone cost](/guides/cost/understand-cost) * [Download a usage report](/admin/billing/download-usage-report) # Understand Pinecone cost Source: https://docs.pinecone.io/guides/cost/understand-cost Understand how Pinecone bills read units, write units, storage, egress, and embedding for full-text search, semantic search, and hybrid search. Pinecone serverless is usage-based, so you pay for the data you store and the operations you run. Four metrics meter index usage: [read units](#read-units), [write units](#write-units), [storage](#storage), and [egress](#egress). [Imports](#imports), [backups](#backups-and-restores), [embedding](#embedding), and [reranking](#reranking) are billed on their own. Many small workloads fit within the free [Starter plan](https://www.pinecone.io/pricing/). [Full-text search](/guides/search/full-text-search) on a document index, semantic search on a legacy vector index, and [hybrid search](/guides/search/hybrid-search) that combines the two are all metered by the same four metrics. > [!TIP] > > This page explains how usage is measured. For current rates, see [Pricing](https://www.pinecone.io/pricing/). For ways to spend less, see [Save on Pinecone costs](/guides/cost/save-on-costs). ## 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/rate-limits#monthly-usage-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** > [accordion] Usage below monthly minimum > > * 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). > [accordion] Usage exceeds monthly minimum > > * 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). > [!NOTE] > > Purchasing prepaid credits isn't available through cloud marketplace billing. To purchase prepaid credits through a cloud marketplace, contact [ar@pinecone.io](mailto:ar@pinecone.io). ## Read units A read unit (RU) measures the compute, I/O, and network resources a read request uses. Pinecone bills these read requests in RUs: * [Query](#query) * [Fetch](#fetch) * [List](#list) * [Full-text search](#full-text-search) > [!TIP] > > Read responses include the number of RUs used, which you can use to [monitor read costs](/guides/cost/check-usage-per-request#read-units). > [!NOTE] > > Indexes built on [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) aren't subject to read unit limits for query, fetch, list, and full-text search operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) guide. ### Query 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). > [!NOTE] > > Parameters that affect the size of the query response, such as `top_k`, `include_metadata`, and `include_values`, don't affect query cost. Only the size of the namespace does. ### 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 doesn't increase the number of RUs used. A fetch request always uses at least 1 RU. > [!NOTE] > > [Fetching records by metadata](/guides/legacy/vectors-api/fetch-vectors#fetch-records-by-metadata) uses the same cost model as fetching by ID: 1 RU for every 10 records fetched. ### List A list request uses 1 RU and returns up to 100 IDs. ### Full-text search Searching a [document index](/guides/search/full-text-search) uses 1 RU for every 1 GB of namespace size, with a minimum of 0.25 RUs per search, the same as a [query](#query). This holds whether the request ranks by keyword relevance or by vector similarity. A document index can declare `string` fields with `full_text_search` enabled and a `dense_vector` field in one schema, and each request ranks by one of them. So a [hybrid search](/guides/search/hybrid-search) that narrows candidates with a [text-match filter](/guides/search/filter-by-metadata#text-match-filters) and then ranks what remains with a `dense_vector` search is billed as one read request. Running a separate keyword search and dense search and merging the results client-side is billed as two. ## Write units A write unit (WU) measures the storage and compute resources a write request uses. Pinecone bills these write requests in WUs: * [Upsert](#upsert) * [Update](#update) * [Delete](#delete) > [!NOTE] > > Writes to a [document index](/guides/get-started/key-terms#document-index) use the same cost models as writes to a legacy vector index. The formulas below apply to both. ### 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 also uses 1 WU for each 1 KB of the existing record. 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 | | 1,000 | 1536 | 1,000 bytes | 7.14 KB | 7,140 | ### 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. 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 | > [!NOTE] > > [Updating records by metadata](/guides/legacy/vectors-api/update-vectors#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. 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 | | 1,000 | 1536 | 1,000 bytes | 7.14 KB | 7,140 | Specifying a non-existent ID or adding the same ID more than once doesn't increase WU use. [Deleting a namespace](/guides/data/manage-namespaces#delete-a-namespace) or [deleting all records in a namespace using `deleteAll`](/guides/legacy/vectors-api/delete-vectors#delete-all-records-in-a-namespace) uses 5 WUs. > [!NOTE] > > [Deleting records by metadata](/guides/legacy/vectors-api/delete-vectors#delete-records-by-metadata) uses the same cost model as deleting by ID: 1 WU for each 1 KB of records deleted. ## Storage Storage is billed monthly per gigabyte (GB) of index size. An index's size is the total size of its records or documents across all namespaces. A document in a document index can include any combination of `string` fields with `full_text_search` enabled, a dense vector, and a sparse vector. A record in a legacy vector index can include a dense vector, a sparse vector, or both. Use the formula that matches your index to calculate total size: > [tab] Document index > > A [document index](/guides/indexes/index-data-overview#document-index) contains documents. Each document's size is its ID, its metadata, and the data in every schema field it holds. > > ```text Calculate size theme={null} > Index size = Number of documents × ( > ID size + > Metadata size + > Total full-text-search field 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 documents. Metadata is every field that isn't declared in the schema. > * `Total full-text-search field size`: The combined UTF-8 byte length of the text in all `string` fields with `full_text_search` enabled, averaged across all documents. A `string` field with [integrated embedding](/guides/indexes/index-data-overview#integrated-embedding) stores its text, which counts here, unless it sets `store_text: false`, in which case only its generated vector counts. If a field has both, count its text here and its generated vector below. > * Each `Dense vector dimension` uses 4 bytes. Sum the dimensions of every dense vector in the document, whether you upsert it or Pinecone generates it for an integrated-embedding field. Omit this term if the schema has no dense vector. > * `Number of non-zero sparse values`: Average number across all documents, including those without sparse vectors. Count every sparse vector in the document, whether you upsert it or Pinecone generates it. Each non-zero value uses 8 bytes. Omit this term if the schema has no sparse vector. > > These examples assume 8-byte IDs: > > | Documents | Avg total full-text-search field size | Dense vector dimensions | Avg number of non-zero sparse values | Avg metadata size | Index size | > | :- | :- | :- | :- | :- | :- | > | 500,000 | 2,000 bytes | None | None | 500 bytes | 1.25 GB | > | 1,000,000 | 5,000 bytes | 1024 | None | 1,000 bytes | 10.1 GB | > | 5,000,000 | 2,000 bytes | 768 | 100 | 500 bytes | 31.9 GB | > > > [!NOTE] > > > > Example: 1,000,000 documents × (8-byte ID + 5,000 bytes of full-text-search text + (1024 dense vector dimensions × 4 bytes) + 1,000 bytes of metadata) = 10.1 GB > [tab] Index of dense vectors > > An [index of dense vectors](/guides/indexes/index-data-overview#indexes-with-dense-vectors) contains records with one dense vector each. > > > [!NOTE] > > > > Records can also contain sparse vectors (when the index metric is set to `dotproduct`), which can be useful for [hybrid search](/guides/legacy/vectors-api/hybrid-search-single-index). To learn how to calculate size in that case, see [Index with both dense and sparse vectors](#index-with-both-dense-and-sparse-vectors). > > ```text Calculate size (assuming no sparse vectors) theme={null} > 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. > > 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 | > > > [!NOTE] > > > > Example: 500,000 records × (8-byte ID + (768 dense vector dimensions × 4 bytes) + 500 bytes of metadata) = 1.79 GB > [tab] Index of sparse vectors > > An [index of sparse vectors](/guides/indexes/index-data-overview#indexes-with-sparse-vectors) contains records with one sparse vector each. > > ```text Calculate size theme={null} > 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. > > 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 | > > > [!NOTE] > > > > Example: 500,000 records × (8-byte ID + (10 non-zero sparse values × 8 bytes) + 500 bytes of metadata) = 0.29 GB > [tab] Index with both dense and sparse vectors > > An [index with both dense and sparse vectors](/guides/legacy/vectors-api/hybrid-search-single-index) contains records that each have one dense vector and an optional sparse vector. > > ```text Calculate size theme={null} > 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. > > 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 | > > > [!NOTE] > > > > 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 or document data returned (IDs, scores, vector values, text fields, and metadata). Egress is metered on read requests that return per-record or per-document data: * [Query](/guides/legacy/vectors-api/query-vectors) on a legacy vector index * [Fetch](/guides/data/fetch-data) (records and documents, by ID and by metadata) * [List](/guides/data/list-record-ids) (record and document IDs) * [Text search](/guides/legacy/records-api/search-with-text) on a legacy integrated index * Search on a document index, whether it ranks by [full-text search](/guides/search/full-text-search) or by vector similarity Write requests (upsert, update, delete, import), index statistics (such as `describe_index_stats`), and index management requests aren't metered for egress. Egress applies to indexes that use [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview) as well as on-demand indexes, because it depends on the data returned to you rather than on the hardware serving the read. > [!NOTE] > > Egress accrues on all bytes returned by in-scope reads, including IDs, scores, and metadata. Leaving vector values out of a [query](/guides/search/search-overview) response (`include_values=false`, the default) lowers egress, but it doesn't exempt the request, because IDs and scores are still returned. `fetch` always returns values, so use `query` when you're searching and only need IDs or metadata. ### Egress allowance Each plan includes a monthly egress allowance, which resets at the start of each billing period: | Plan | Monthly egress allowance | | :- | :- | | Starter | 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. * **Flat-fee plans (Starter, 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/data/import-data) is the most cost-effective way to load large numbers of records into an index. An import is billed by the size of the records it reads, whether or not they import successfully. If the import fails (e.g., after it reads a vector of the wrong dimension in an import with `on_error="abort"`), you're still charged for the records read. If the import fails because of an internal system error, you aren't charged, and the import returns the error message `"We were unable to process your request. If the problem persists, please contact us at https://support.pinecone.io"`. ## Backups and restores A [backup](/guides/indexes/backups-overview) is a static copy of a serverless index. Storing a backup and [restoring an index](/guides/indexes/restore-an-index) from a backup are both billed by the size of the index. [Restoring a backup into a different region](/guides/indexes/restore-an-index#restore-to-a-different-region) also incurs a cross-region transfer fee, charged per GB on top of the restore cost. The rate depends on the cloud provider and the backup's region. Restoring into the same region as the backup doesn't incur this fee. On your invoice, the fee appears as **Serverless Cross-Region Transfer**. ## Embedding Pinecone hosts several [embedding models](/guides/indexes/index-configuration#embedding-models). You can embed your data as an integrated part of upserting and querying, or as a standalone operation. Embedding is billed by the number of [tokens](https://www.pinecone.io/learn/tokenization/) in a request. The more words in your passage or query, the more tokens it generates. For example, if you generate embeddings for the query, "What is the maximum diameter of a red pine?", Pinecone generates 10 tokens, then converts them into an embedding. If your plan's rate is \$0.08 per million tokens, this call costs \$0.0000008. To learn more about tokenization, see [Choosing an embedding model](https://www.pinecone.io/learn/series/rag/embedding-models-rundown/). > [!TIP] > > Embedding requests return the total tokens generated. You can use this information to [monitor and manage embedding costs](/guides/cost/check-usage-per-request#embedding-tokens). ## Reranking Pinecone hosts several [reranking models](/guides/search/rerank-results#reranking-models). You can rerank results as an integrated part of a query, or as a standalone operation. Reranking is billed by the number of requests to the reranking model. ## 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/). On the Enterprise plan or with the add-on, HIPAA compliance requires you to [configure audit logs](/admin/security/configure-audit-logs). On the Standard plan, 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 > [!NOTE] > > 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, [submit a HIPAA request](https://www.pinecone.io/contact/hipaa/). The Pinecone team reviews your request and guides you through activation. ## See also * [Save on Pinecone costs](/guides/cost/save-on-costs) * [Check usage per request](/guides/cost/check-usage-per-request) * [Download a usage report](/admin/billing/download-usage-report) * [Pricing](https://www.pinecone.io/pricing/) # Check data freshness Source: https://docs.pinecone.io/guides/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 data is 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 > [!NOTE] > > 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 don't 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 data 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: 2026-07" \ -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: 2026-07" \ -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 doesn't 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 isn't 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, don't 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 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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) 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/indexes/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/indexes/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, 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/v7/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/indexes/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/indexes/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: 2026-07" ``` 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 } ``` # Data ingestion overview Source: https://docs.pinecone.io/guides/data/data-ingestion-overview Compare data ingestion options in Pinecone: bulk import from object storage, upsert operations, and hosted embedding via the Inference API. > [!TIP] > > To control costs when ingesting large datasets (10,000,000+ records), use [import](/guides/data/import-data) instead of upsert. ## Import from object storage [Importing from object storage](/guides/data/import-data) is the most efficient and cost-effective method to load large numbers of documents into an index. You store your data in object storage ([JSON Lines (JSONL)](https://jsonlines.org/) for document indexes, Parquet for legacy vector indexes), integrate your object storage with Pinecone, and then start an asynchronous, long-running operation that imports and indexes your data. > [!NOTE] > > 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, one record or document at a time, or in batches, use the [upsert](/guides/data/upsert-data) operation. [Batch upserting](/guides/data/upsert-data#upsert-in-batches) can improve throughput performance and is a good option for larger numbers of records or documents if you can't work around import's current [limitations](/guides/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 [Generate vectors](/reference/api/latest/inference/generate-vectors) operation for standalone embedding to turn text into vectors without writing to an index. That differs from [integrated embedding](/guides/search/integrated-embedding) on a document index, where Pinecone embeds a field's text when you upsert or search. To see how many embedding tokens a request consumes, see [Embedding tokens](/guides/cost/check-usage-per-request#embedding-tokens). ## Ingestion cost * To understand how cost is calculated for imports, see [Import cost](/guides/cost/understand-cost#imports). * To understand how cost is calculated for upserts, see [Write unit pricing](/guides/cost/understand-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 data is visible to queries. You can view index stats to [check data freshness](/guides/data/check-data-freshness). # Delete data Source: https://docs.pinecone.io/guides/data/delete-data Delete Pinecone documents from a namespace in a document index by ID or metadata filter, or delete every document the namespace holds. This page shows you how to delete documents by ID, by metadata filter, or all at once from a [namespace](/guides/indexes/index-data-overview#namespaces) in a document index. For a legacy vector index, see [Delete vectors](/guides/legacy/vectors-api/delete-vectors). > [!TIP] > > Deletes consume [write units (WUs)](/guides/cost/understand-cost#write-units). See [Understand Pinecone cost](/guides/cost/understand-cost#delete) for how delete cost is calculated. ## Delete documents In an index with a document schema, delete documents by ID, by metadata filter, or delete the whole namespace's contents. A request specifies exactly one of `ids`, `filter`, or `delete_all`, and can name up to 1,000 IDs. ### Delete documents by ID To delete specific documents, pass their IDs: ```Python Python theme={null} # pip install --upgrade pinecone 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/indexes/target-an-index index = pc.index(host="INDEX_HOST") index.documents.delete(namespace="articles", ids=["doc-1", "doc-2"]) ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/namespaces/articles/documents/delete" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "ids": ["doc-1", "doc-2"] }' ``` ### Delete documents by metadata To delete every document matching a [metadata filter expression](/guides/indexes/index-data-overview#metadata-filter-expressions), pass a `filter`. The response reports how many documents matched: ```Python Python theme={null} # Connect to an index as shown above. response = index.documents.delete( namespace="articles", filter={"category": {"$eq": "news"}}, ) print(response.matched_records) ``` ```bash curl theme={null} curl "https://$INDEX_HOST/namespaces/articles/documents/delete" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "filter": { "category": { "$eq": "news" } } }' ``` ```json theme={null} { "matched_records": 6 } ``` ### Delete all documents in a namespace To empty a namespace without deleting the namespace itself, pass `delete_all`: ```Python Python theme={null} # Connect to an index as shown above. index.documents.delete(namespace="articles", delete_all=True) ``` ```bash curl theme={null} curl "https://$INDEX_HOST/namespaces/articles/documents/delete" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "delete_all": true }' ``` A delete by ID and a `delete_all` return an empty response body. Only a filtered delete reports `matched_records`. > [!NOTE] > > [Text-match operators](/guides/search/filter-by-metadata#text-match-filters) (`$match_phrase`, `$match_all`, `$match_any`) aren't supported in a filtered delete, and a request carrying one is rejected with a `400`. To delete documents by text match, [search](/guides/search/full-text-search) for them first and delete the IDs the search returns. For the full request and response schema, see [Delete documents](/reference/api/latest/data-plane/delete_documents). ## Delete an entire namespace To delete an entire namespace and all of its documents, see [Delete a namespace](/guides/data/manage-namespaces#delete-a-namespace). ## Delete an entire index To remove all documents from an index, [delete the index](/guides/indexes/manage-indexes#delete-an-index) and [recreate it](/guides/indexes/create-an-index). ## Data freshness Pinecone is eventually consistent, so there can be a slight delay before new or changed documents are visible to queries. You can view index stats to [check data freshness](/guides/data/check-data-freshness). # Design for multitenancy Source: https://docs.pinecone.io/guides/data/design-for-multitenancy Design multitenancy in Pinecone by choosing between namespace-per-tenant isolation and metadata filtering, with their cost and performance tradeoffs. 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 multitenancy is to use [namespaces](/guides/indexes/index-data-overview#namespaces) to separate data by tenant. With this approach, each tenant has their own namespace, and searches only scan that tenant's data, resulting in better performance and lower costs. * **Lower search costs and faster performance**: Search cost is based on namespace size. If you have 100 tenants with 1 GB each, searching one tenant's namespace costs 1 RU and scans only 1 GB. With metadata filtering in a single namespace (100 GB total), the same search costs 100 RUs and scans all 100 GB, even though the filter narrows results. * **Natural isolation**: Reduces the risk of application bugs that could search the wrong tenant's data (for example, by passing an incorrect filter value). For a complete implementation guide with examples, see [Implement multitenancy](/guides/data/implement-multitenancy). ## Avoid filtering by high-cardinality IDs A common anti-pattern is storing all data in a single namespace and using metadata filters to scope searches to specific users. The examples on this page search a `dense_vector` field named `embedding`: ```python Python theme={null} # Anti-pattern: Filtering by many user IDs 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/indexes/target-an-index index = pc.index(host="INDEX_HOST") query_vector = [0.1, 0.2, 0.3, ...] # Your query vector results = index.documents.search( namespace="example-namespace", top_k=10, score_by=[ {"type": "dense_vector", "fields": ["embedding"], "values": query_vector} ], filter={ "allowed_user_ids": {"$in": ["user_1", "user_2", ..., "user_10000"]} }, ) for match in results.matches: print(match._id, match._score) ``` ```javascript JavaScript theme={null} // Anti-pattern: Filtering by many user IDs 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/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST', namespace: 'example-namespace' }); const queryVector = [0.1, 0.2, 0.3, ...]; // Your query vector const results = await index.documents.search({ topK: 10, scoreBy: [ { type: 'dense_vector', fields: ['embedding'], values: queryVector }, ], filter: { allowed_user_ids: { $in: ["user_1", "user_2", ..., "user_10000"] } } }); console.log(results); ``` ```go Go theme={null} // Anti-pattern: Filtering by many user IDs package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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/indexes/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.1, 0.2, 0.3, ...} // Your query vector userIds := []interface{}{"user_1", "user_2", /* ... up to 10,000 values */} res, err := idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{ TopK: 10, ScoreBy: []pinecone.DocumentScoringMethod{ {Type: pinecone.DocumentScoringTypeDenseVector, Fields: []string{"embedding"}, Values: &queryVector}, }, Filter: map[string]interface{}{ "allowed_user_ids": map[string]interface{}{"$in": userIds}, }, }) if err != nil { log.Fatalf("Failed to search documents: %v", err) } fmt.Println(prettifyStruct(res)) } ``` ```bash curl theme={null} # Anti-pattern: Filtering by many user IDs PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/namespaces/example-namespace/documents/search" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "top_k": 10, "score_by": [ { "type": "dense_vector", "fields": ["embedding"], "values": [0.1, 0.2, 0.3, ...] } ], "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/operation-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 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/indexes/target-an-index index = pc.index(host="INDEX_HOST") query_vector = [0.1, 0.2, 0.3, ...] # Your query vector results = index.documents.search( namespace="example-namespace", top_k=10, score_by=[ {"type": "dense_vector", "fields": ["embedding"], "values": query_vector} ], filter={ "$or": [ {"organization_id": {"$eq": "org_A"}}, {"project_id": {"$eq": "project_B"}} ] }, ) for match in results.matches: print(match._id, match._score) ``` ```javascript JavaScript theme={null} // Better: Filter by organization or role instead of individual users 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/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST', namespace: 'example-namespace' }); const queryVector = [0.1, 0.2, 0.3, ...]; // Your query vector const results = await index.documents.search({ topK: 10, scoreBy: [ { type: 'dense_vector', fields: ['embedding'], values: queryVector }, ], filter: { $or: [ { organization_id: { $eq: "org_A" } }, { project_id: { $eq: "project_B" } } ] } }); console.log(results); ``` ```go Go theme={null} // Better: Filter by organization or role instead of individual users package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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/indexes/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.1, 0.2, 0.3, ...} // Your query vector res, err := idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{ TopK: 10, ScoreBy: []pinecone.DocumentScoringMethod{ {Type: pinecone.DocumentScoringTypeDenseVector, Fields: []string{"embedding"}, Values: &queryVector}, }, Filter: 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"}}, }, }, }) if err != nil { log.Fatalf("Failed to search documents: %v", err) } fmt.Println(prettifyStruct(res)) } ``` ```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 "https://$INDEX_HOST/namespaces/example-namespace/documents/search" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "top_k": 10, "score_by": [ { "type": "dense_vector", "fields": ["embedding"], "values": [0.1, 0.2, 0.3, ...] } ], "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 | > [!WARNING] > > Avoid filtering by large lists of individual user IDs. For the limits, the performance and cost impact, and the alternatives, see [Avoid filtering by high-cardinality IDs](#avoid-filtering-by-high-cardinality-ids). For a complete step-by-step implementation guide, see [Implement multitenancy](/guides/data/implement-multitenancy). # Fetch data Source: https://docs.pinecone.io/guides/data/fetch-data Retrieve Pinecone documents from a namespace in a document index by ID or metadata filter to inspect their fields and metadata. This page shows you how to fetch documents by ID or by metadata filter from a [namespace](/guides/indexes/index-data-overview#namespaces) in a document index. For a legacy vector index, see [Fetch vectors](/guides/legacy/vectors-api/fetch-vectors). You can also fetch data in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes/-/browser). > [!TIP] > > Fetches consume [read units (RUs)](/guides/cost/understand-cost#read-units). See [Understand Pinecone cost](/guides/cost/understand-cost#fetch) for how fetch cost is calculated. ## Fetch documents In an index with a document schema, fetch documents by ID or by metadata filter. A request specifies exactly one of `ids` or `filter`, and can name up to 1,000 IDs. `include_fields` selects which fields come back, and omitting it returns all of them. ### Fetch documents by ID To fetch specific documents, pass their IDs: ```Python Python theme={null} # pip install --upgrade pinecone 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/indexes/target-an-index index = pc.index(host="INDEX_HOST") response = index.documents.fetch( namespace="articles", ids=["doc-1", "doc-2"], include_fields=["title", "body"], ) ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/namespaces/articles/documents/fetch" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "ids": ["doc-1", "doc-2"], "include_fields": ["title", "body"] }' ``` The response keys each document by its ID: ```json theme={null} { "documents": { "doc-1": { "_id": "doc-1", "title": "First", "body": "First body text." }, "doc-2": { "_id": "doc-2", "title": "Second", "body": "Second body text." } }, "namespace": "articles", "usage": { "read_units": 1, "egress_bytes": 98 } } ``` ### Fetch documents by metadata To fetch every document matching a [metadata filter expression](/guides/indexes/index-data-overview#metadata-filter-expressions), pass a `filter` instead of `ids`: ```Python Python theme={null} # Connect to an index as shown above. response = index.documents.fetch( namespace="articles", filter={"category": {"$eq": "news"}}, include_fields=["*"], ) ``` ```bash curl theme={null} curl "https://$INDEX_HOST/namespaces/articles/documents/fetch" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "filter": { "category": { "$eq": "news" } }, "include_fields": ["*"] }' ``` A filtered fetch returns one page at a time, holding 100 documents by default and 10,000 at most. When more documents match, the response carries a `pagination.next` token. Pass it back as `pagination_token` to get the next page, and stop when the response has no `pagination` token. In the REST API, `limit` sets the page size. Unlike a filtered update or delete, a filtered fetch accepts the [text-match operators](/guides/search/filter-by-metadata#text-match-filters) `$match_phrase`, `$match_all`, and `$match_any` on full-text fields, so you can fetch documents by their text without running a search. For the full request and response schema, see [Fetch documents](/reference/api/latest/data-plane/fetch_documents). ## Data freshness Pinecone is eventually consistent, so there can be a slight delay before new or changed documents are visible to queries. You can view index stats to [check data freshness](/guides/data/check-data-freshness). # Implement multitenancy Source: https://docs.pinecone.io/guides/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 document index with one namespace per tenant. For when to use namespaces, metadata filtering, or other approaches, see [Design for multitenancy](/guides/data/design-for-multitenancy). ## How it works In Pinecone, an [index](/guides/indexes/index-data-overview) is the highest-level organizational unit of data, where you define a schema for the documents stored in the index, such as the dimension and similarity metric of a `dense_vector` field. Within an index, documents are stored in [namespaces](/guides/indexes/index-data-overview#namespaces), and all [upserts](/guides/data/upsert-data), [searches](/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 searches to that namespace: ![Diagram of a multitenant SaaS index with three namespaces, one per customer, each holding documents 1 through n. A query on customer 1's data targets namespace 1, and a new document for customer 3 goes to namespace 3.](https://mintcdn.com/pinecone/qjxrsVApPT3I4Dwt/images/multitenant-saas-namespaces-light.svg?fit=max\&auto=format\&n=qjxrsVApPT3I4Dwt\&q=85\&s=290ae697e92b15148b8fa36709755b8c) 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: ![Diagram of a RAG index and a semantic search index, each with one namespace per customer. Queries on customer 1's data target namespace 1 in each index.](https://mintcdn.com/pinecone/qjxrsVApPT3I4Dwt/images/multitenant-saas-indexes-light.svg?fit=max\&auto=format\&n=qjxrsVApPT3I4Dwt\&q=85\&s=6ee475750713c79c223cd260d29bf113) ### Benefits * **Tenant isolation:** In the [serverless architecture](/guides/get-started/architecture), each namespace is stored separately, so using namespaces provides physical isolation of data between tenants. This reduces the risk of application bugs that could search the wrong tenant's data. * **No noisy neighbors:** Reads and writes always target a single namespace, so the behavior of one tenant doesn't affect other tenants. * **No maintenance effort:** Serverless indexes scale automatically based on usage; you don't configure or manage any compute or storage resources. * **Cost efficiency:** Search cost is based on namespace size (1 RU per 1 GB). With 100 tenants of 1 GB each, searching one tenant's namespace costs 1 RU. Using metadata filtering in a single 100 GB namespace would cost 100 RUs for the same search, because it scans all data regardless of filters. * **Simple tenant offboarding:** To offboard a tenant, you just [delete the relevant namespace](/guides/data/manage-namespaces#delete-a-namespace). This is a lightweight and almost instant operation. > [!NOTE] > > [Namespaces per serverless index](/reference/api/database-limits/object-limits) vary by plan (100 on Starter to 1,000,000 on Enterprise). Pinecone can accommodate more for specific use cases. If your application needs a higher limit, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ## Set up one namespace per tenant ### 1. Create a document index Serverless indexes [separate storage from compute](/guides/get-started/architecture), 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 document index](/guides/indexes/create-an-index#create-a-document-index), set the cloud and region where the index should be deployed in `deployment`, and declare the fields to index in `schema`. This example declares one `dense_vector` field, `embedding`, with 8 dimensions and the cosine metric: ```python Python theme={null} from pinecone import Pinecone, SchemaBuilder pc = Pinecone(api_key="YOUR_API_KEY") schema = ( SchemaBuilder() .add_dense_vector_field(name="embedding", dimension=8, metric="cosine") .build() ) pc.indexes.create( name="multitenant-app", deployment={"deployment_type": "managed", "cloud": "aws", "region": "us-east-1"}, schema=schema, ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.indexes.create({ name: 'multitenant-app', deployment: { deploymentType: 'managed', cloud: 'aws', region: 'us-east-1', }, schema: { fields: { embedding: { type: 'dense_vector', dimension: 8, metric: 'cosine', }, }, }, }); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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.CreateIndex(ctx, &pinecone.CreateIndexRequest{ Name: "multitenant-app", Deployment: &pinecone.IndexDeployment{ Managed: &pinecone.ManagedDeployment{ Cloud: pinecone.CloudAWS, Region: "us-east-1", }, }, Schema: pinecone.IndexSchema{ Fields: map[string]pinecone.IndexSchemaField{ "embedding": { DenseVector: &pinecone.DenseVectorField{ Dimension: 8, Metric: pinecone.IndexMetricCosine, }, }, }, }, }) if err != nil { log.Fatalf("Failed to create index: %v", err) } fmt.Printf("Successfully created 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: 2026-07" \ -d '{ "name": "multitenant-app", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "embedding": { "type": "dense_vector", "dimension": 8, "metric": "cosine" } } } }' ``` Before you upsert, [wait for the index to be ready](/guides/indexes/create-an-index#wait-for-the-index-to-be-ready). The Python SDK waits by default. ### 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/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/indexes/index-data-overview#namespaces), specify the namespace when you first [upsert](/guides/data/upsert-data) the tenant's documents. For example, the following code upserts documents for `tenant1` and `tenant2` into the `multitenant-app` index: ```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/indexes/target-an-index index = pc.index(host="INDEX_HOST") index.documents.upsert( namespace="tenant1", documents=[ {"_id": "A", "embedding": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1]}, {"_id": "B", "embedding": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]}, {"_id": "C", "embedding": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]}, {"_id": "D", "embedding": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]}, ], ) index.documents.upsert( namespace="tenant2", documents=[ {"_id": "E", "embedding": [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5]}, {"_id": "F", "embedding": [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6]}, {"_id": "G", "embedding": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7]}, {"_id": "H", "embedding": [0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8]}, ], ) ``` ```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/indexes/target-an-index const tenant1 = pc.index({ host: 'INDEX_HOST', namespace: 'tenant1' }); const tenant2 = pc.index({ host: 'INDEX_HOST', namespace: 'tenant2' }); await tenant1.documents.upsert({ documents: [ { _id: 'A', embedding: [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1] }, { _id: 'B', embedding: [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2] }, { _id: 'C', embedding: [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3] }, { _id: 'D', embedding: [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4] }, ], }); await tenant2.documents.upsert({ documents: [ { _id: 'E', embedding: [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5] }, { _id: 'F', embedding: [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6] }, { _id: 'G', embedding: [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7] }, { _id: 'H', embedding: [0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8] }, ], }); ``` ```go Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v7/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/indexes/target-an-index tenant1, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "tenant1"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } // This reuses the connection of tenant1 while targeting a different namespace tenant2 := tenant1.WithNamespace("tenant2") _, err = tenant1.UpsertDocuments(ctx, &pinecone.UpsertDocumentsRequest{ Documents: []pinecone.Document{ {"_id": "A", "embedding": []float32{0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1}}, {"_id": "B", "embedding": []float32{0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2}}, {"_id": "C", "embedding": []float32{0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3}}, {"_id": "D", "embedding": []float32{0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4}}, }, }) if err != nil { log.Fatalf("Failed to upsert documents: %v", err) } _, err = tenant2.UpsertDocuments(ctx, &pinecone.UpsertDocumentsRequest{ Documents: []pinecone.Document{ {"_id": "E", "embedding": []float32{0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5}}, {"_id": "F", "embedding": []float32{0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6}}, {"_id": "G", "embedding": []float32{0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7}}, {"_id": "H", "embedding": []float32{0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8}}, }, }) if err != nil { log.Fatalf("Failed to upsert documents: %v", err) } } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/namespaces/tenant1/documents/upsert" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "documents": [ { "_id": "A", "embedding": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1] }, { "_id": "B", "embedding": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2] }, { "_id": "C", "embedding": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3] }, { "_id": "D", "embedding": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4] } ] }' curl "https://$INDEX_HOST/namespaces/tenant2/documents/upsert" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "documents": [ { "_id": "E", "embedding": [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5] }, { "_id": "F", "embedding": [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6] }, { "_id": "G", "embedding": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7] }, { "_id": "H", "embedding": [0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8] } ] }' ``` When upserting additional documents for a tenant, or when [updating](/guides/data/update-data) or [deleting](/guides/data/delete-data) documents for a tenant, specify the tenant's namespace. For example, the following code updates the `embedding` field of document `A` in `tenant1`: ```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/indexes/target-an-index index = pc.index(host="INDEX_HOST") index.documents.update( namespace="tenant1", documents=[ {"_id": "A", "embedding": [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8]}, ], ) ``` ```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/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST', namespace: 'tenant1' }); await index.documents.update({ documents: [ { _id: 'A', embedding: [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8] }, ], }); ``` ```go Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v7/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/indexes/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "tenant1"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } _, err = idxConnection.UpdateDocuments(ctx, &pinecone.UpdateDocumentsRequest{ Documents: []pinecone.Document{ {"_id": "A", "embedding": []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 document: %v", err) } } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/namespaces/tenant1/documents/update" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "documents": [ { "_id": "A", "embedding": [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8] } ] }' ``` ### 3. Search tenant data In a multitenant solution, you need to ensure that the searches of one tenant don't affect the experience of other tenants. To achieve this in Pinecone, target each tenant's [searches](/guides/search/search-overview) at the namespace for the tenant. For example, the following code searches only `tenant2` for the 3 documents that are most similar to an example query vector: ```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/indexes/target-an-index index = pc.index(host="INDEX_HOST") results = index.documents.search( namespace="tenant2", top_k=3, score_by=[ { "type": "dense_vector", "fields": ["embedding"], "values": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7], } ], ) for match in results.matches: print(match._id, match._score) ``` ```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/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST', namespace: 'tenant2' }); const results = await index.documents.search({ topK: 3, scoreBy: [ { type: 'dense_vector', fields: ['embedding'], values: [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7] }, ], }); for (const match of results.matches) { console.log(match._id, match._score); } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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/indexes/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "tenant2"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } queryVector := []float32{0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7} res, err := idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{ TopK: 3, ScoreBy: []pinecone.DocumentScoringMethod{ {Type: pinecone.DocumentScoringTypeDenseVector, Fields: []string{"embedding"}, Values: &queryVector}, }, }) if err != nil { log.Fatalf("Failed to search documents: %v", err) } fmt.Println(prettifyStruct(res)) } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/namespaces/tenant2/documents/search" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "top_k": 3, "score_by": [ { "type": "dense_vector", "fields": ["embedding"], "values": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7] } ] }' ``` ## 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 documents. To achieve this in Pinecone, you just [delete the namespace](/guides/data/manage-namespaces#delete-a-namespace) for the specific tenant. For example, the following code deletes the namespace and all documents for `tenant1`: ```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/indexes/target-an-index index = pc.index(host="INDEX_HOST") index.delete_namespace(name="tenant1") ``` ```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/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST' }); await index.deleteNamespace('tenant1'); ``` ```go Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v7/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/indexes/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, "tenant1") if err != nil { log.Fatalf("Failed to delete namespace: %v", err) } } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X DELETE "https://$INDEX_HOST/namespaces/tenant1" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" ``` ## Alternative: Metadata filtering When tenant isolation isn't a strict requirement, or when you need to search across multiple tenants simultaneously, you can store all documents in a single namespace and use metadata fields to assign documents to tenants. At search time, you can then [filter by metadata](/guides/indexes/index-data-overview#metadata). > [!WARNING] > > This approach has significant performance and cost tradeoffs compared to using namespaces: > > * Higher search costs: Searches 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 search 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/operation-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 multitenancy](/guides/data/design-for-multitenancy). 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 data Source: https://docs.pinecone.io/guides/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 documents 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). > [!NOTE] > > This feature is available on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). ## Before you import Before you can import data, ensure you have a serverless index, a storage integration, and data uploaded to an Amazon S3 bucket, Google Cloud Storage bucket, or Azure Blob Storage container. Your uploaded data must be in [JSON Lines](https://jsonlines.org/) (JSONL) format for a document index, or Parquet for a [legacy vector index](/guides/legacy/vectors-api/import-vectors). If your source data isn't already in that format, prepare it in that format before uploading. ## 1. Create an index [Create a serverless index](/guides/indexes/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**… | ✅ | ✅ | ✅ | ## 2. Add a storage integration To import from a public data source, a storage integration isn't required. However, to import 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/storage-integrations/integrate-with-amazon-s3) * [Integrate with Google Cloud Storage](/guides/storage-integrations/integrate-with-google-cloud-storage) * [Integrate with Azure Blob Storage](/guides/storage-integrations/integrate-with-azure-blob-storage) ## 3. Prepare your data **1. Create a directory for each namespace** 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/ ``` > [!TIP] > > To import into the default namespace, use a subdirectory called `__default__`. The default namespace must be empty. **2. Create a data file for each namespace** For each namespace, create one or more files defining the data to import. To import into a namespace in an [index with a document schema](/guides/indexes/data-modeling#documents), use JSONL (`.jsonl`, or gzip-compressed `.jsonl.gz`) files. Each line is one [document](/guides/get-started/key-terms#document), identical in shape to a document you would pass to the [Upsert documents](/reference/api/latest/data-plane/upsert_documents) operation: | Field | JSON type | Description | | - | - | - | | `_id` | `string` | Required. Unique identifier for each document within the namespace. | | Each schema field | Depends on the field's type | Encode each schema-declared field by its type: a full-text `string` field as a JSON string; a `dense_vector` field as an array of floats matching the schema's `dimension`; a `sparse_vector` field as `{"indices": [...], "values": [...]}`. A document doesn't need to populate every declared field, but it must include `_id` and at least one schema field. | | Any other field | `string`, number, boolean, or array of strings | Optional. Stored and auto-indexed as filterable [metadata](/guides/get-started/key-terms#metadata). Field names can't start with `_` or `$`. | For example, for a schema with a full-text `body` field and a `dense_vector` `embedding` field: ```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} ``` For the full file format, per-field encoding, and directory layout, see [Prepare document-schema files](#prepare-document-schema-files-jsonl). To import into a legacy vector index, use Parquet files instead. See [Import vectors](/guides/legacy/vectors-api/import-vectors). **3. Upload the files** Upload the files into the relevant subdirectory. For example, if you have subdirectories for the namespaces `example_namespace1` and `example_namespace2` and upload 4 files into each, your directory structure would look as follows after the upload. Files use the `.jsonl` or `.jsonl.gz` extension for document indexes, or `.parquet` for legacy vector indexes: ``` / --// ----/example_namespace1/ ------0. ------1. ------2. ------3. ----/example_namespace2/ ------4. ------5. ------6. ------7. ``` ## 4. Import data into an index > [!WARNING] > > Review [import limits](#import-limits) before starting an import. > [!NOTE] > > The same request imports [JSONL files](#prepare-document-schema-files-jsonl) into a document index or [Parquet files](/guides/legacy/vectors-api/import-vectors) into a legacy vector index. You can't import into an index whose schema declares `embed` or `sparse_embed`. Use the [Start import](/reference/api/latest/data-plane/start_import) operation to start an asynchronous import from object storage into an index. * For `uri`, specify the URI of the bucket and import directory containing the namespaces and 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. > [!NOTE] > > An Integration ID isn't needed to import from a public bucket. * For `error_mode`, use `continue` or `abort`. * With `abort`, the operation stops if any documents fail to import. * With `continue`, the operation continues on error, but there isn't any notification about which documents, if any, failed to import. To see how many 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/indexes/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/indexes/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.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, "continue"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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/indexes/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, &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/indexes/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-07" \ -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/architecture#index-builder) indexes the data, 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`. > [!TIP] > > 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**. ## 5. Track import progress The amount of time required for an import depends on various factors, including: * The number of documents to import * The number of namespaces to import, and the number of documents 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 an 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/indexes/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/indexes/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/v7/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/indexes/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/indexes/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-07" ``` 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" } ``` ## Prepare document-schema files (JSONL) For indexes with a document schema, import files are [JSON Lines](https://jsonlines.org/) (`.jsonl`), optionally gzip-compressed (`.jsonl.gz`), instead of Parquet. Each line is one document, identical in shape to a document you would pass to the [Upsert documents](/reference/api/latest/data-plane/upsert_documents) operation, and validated through the same code path, so a document that upserts cleanly imports cleanly. ### File format 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. * Each document must include at least one schema-declared field; it doesn't need to populate every declared field. * 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`. * 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](/guides/search/full-text-search#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](/reference/api/latest/data-plane/upsert_documents) apply. ### Directory layout Lay files out by namespace, as described in [Prepare your data](#3-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/legacy/vectors-api/import-vectors) (`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") ``` ## 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. > [tab] Python SDK > > 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/indexes/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=" > } > } > ``` > > > [!TIP] > > > > 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. > [tab] Other SDKs > > 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/indexes/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/v7/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/indexes/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, &pinecone.ListImportsRequest{Limit: &limit}) > 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, &pinecone.ListImportsRequest{Limit: &limit, PaginationToken: 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/indexes/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-07" > ``` ### Cancel an import The [Cancel an import](/reference/api/latest/data-plane/cancel_import) operation cancels an import if it isn't 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/indexes/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/indexes/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/v7/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/indexes/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/indexes/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-07" ``` ```json Response theme={null} {} ``` > [!TIP] > > 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 > [!NOTE] > > If your import exceeds these limits, you'll get an error specifying the limit exceeded. See [Troubleshooting](/guides/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 doesn't apply to indexes with [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview). Bulk import supports indexes without a schema definition (Parquet files) and indexes with document schemas ([JSONL files](/guides/data/import-data#prepare-document-schema-files-jsonl)). Semantic-text (auto-embedded) fields aren't yet supported in document schemas. Also: * You can't import data from an AWS S3 bucket into a Pinecone index hosted on GCP or Azure. * You can't import data from S3 Express One Zone storage. * You can't 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. * You can't import into an index whose schema declares `embed` or `sparse_embed`. To add text that Pinecone embeds, use [upsert](/guides/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. > [accordion] Namespace already exists > > You can't 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 doesn't yet exist. > [accordion] No namespace found > > 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 isn't 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. > [accordion] Parquet files not found > > Each namespace subdirectory must contain Parquet files with data to import. If a namespace subdirectory doesn't 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. > [accordion] Namespace not created (empty subdirectory) > > For document-schema (JSONL) imports, an empty namespace subdirectory behaves differently than for Parquet. A namespace subdirectory that contains no `.jsonl` or `.jsonl.gz` files is silently skipped: the import doesn't create that namespace and doesn't raise an error for it. If a namespace is missing after an import that otherwise succeeded, confirm its subdirectory actually contains importable files. > > If no importable files are found anywhere under the dataset prefix, the import fails with the same `No Parquet files found` error shown above, which says "Parquet files" even for JSONL imports. > [accordion] Invalid import URI > > 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`. > [accordion] Invalid Parquet files > > When a Parquet file isn't 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](#3-prepare-your-data) section. > [accordion] Invalid JSONL files or documents > > For document-schema indexes, import files are JSONL: each line is one JSON document, validated against the index's [schema](#file-format). A line fails if it isn't valid JSON, or if the document doesn't conform to the schema. Each per-document error identifies the file name, row number, and document `_id`: > > ``` > error reading record (file "0.jsonl", row 2, id "doc1"): {reason} > ``` > > Common reasons include: > > ```shell Malformed JSON theme={null} > invalid JSON document: {details} > ``` > > ```shell Empty _id theme={null} > Vector ID must not be empty > ``` > > ```shell Dense-vector dimension mismatch theme={null} > Vector dimension {actual} does not match the dimension of the index {expected} > ``` > > ```shell Reserved field name theme={null} > Document with id '{id}': Field name '{name}' cannot start with '_' (reserved for internal use) > ``` > > ```shell Wrong field type theme={null} > Document with id '{id}': full text search field '{field}' must be a string > ``` > > A document that omits `_id` entirely fails JSON parsing and appears as a malformed-JSON error (`missing field _id`). > > With `errorMode.onError` set to `continue` (the default), invalid documents are skipped and the rest import; with `abort`, the import stops on the first invalid document. If every document in a namespace is skipped, the import fails with `No vectors added, all rows were skipped for namespace: {namespace}`. > > To fix these errors, validate your documents against the [file-format rules](#file-format) before importing. > [accordion] Invalid records > > 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 doesn't 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](#3-prepare-your-data) section. > [accordion] Duplicate records > > Bulk import deduplicates by record ID, not by vector value. If an import contains more than one record with the same ID in the same namespace, only one is kept and the rest are counted as skipped. Which record is kept isn't deterministic. Records that share identical vector values but have different IDs are all imported. > > This applies to both JSONL imports (document indexes) and Parquet imports (legacy vector indexes). To control which record wins, deduplicate your source data by ID before importing. > > **Example scenario:** > If your import file contains: > > ```text theme={null} > id | values > ---|--------- > 1 | [0.1, 0.2, 0.3] > 1 | [0.4, 0.5, 0.6] ← Same ID as the first record; only one of the two is kept > 2 | [0.7, 0.8, 0.9] > ``` > > Two records are imported: `2`, and one of the two records with ID `1`. > [accordion] Import exceeds maximum data size for on-demand > > 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/optimize/dedicated-read-nodes/overview) (which have no total data size limit for imports), or [contact support](https://app.pinecone.io/organizations/-/settings/support/ticket). > > For `.jsonl.gz` files, size is measured as an estimated uncompressed size of 10× the compressed file, so gzip-compressed files count roughly 10× their on-disk size against this limit. ## See also * [Integrate with Amazon S3](/guides/storage-integrations/integrate-with-amazon-s3) * [Integrate with Google Cloud Storage](/guides/storage-integrations/integrate-with-google-cloud-storage) * [Integrate with Azure Blob Storage](/guides/storage-integrations/integrate-with-azure-blob-storage) * [Pinecone's pricing](https://www.pinecone.io/pricing/) # List IDs Source: https://docs.pinecone.io/guides/data/list-record-ids List the IDs of Pinecone documents in a namespace of a document index, filter them by ID prefix, and paginate through the results. This page shows you how to list the IDs in an index [namespace](/guides/indexes/index-data-overview#namespaces), either all of them or just those with a common ID prefix. Listing IDs without the data behind them is a cheap and fast way to check [upserts](/guides/data/upsert-data). For a legacy vector index, see [List vector IDs](/guides/legacy/vectors-api/list-vector-ids). > [!NOTE] > > The `list` endpoint is supported only for serverless indexes. ## List document IDs In an index with a document schema, `list` returns document IDs in sorted order, 100 per page, which is also the maximum page size. Each entry carries only an `_id`. To get the fields of a document, [fetch](/guides/data/fetch-data#fetch-documents) it. ### List all document IDs ```Python Python theme={null} # pip install --upgrade pinecone 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/indexes/target-an-index index = pc.index(host="INDEX_HOST") for doc in index.documents.list(namespace="articles"): print(doc._id) ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/namespaces/articles/documents/list" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "limit": 5 }' ``` The response holds one entry per document, and a `pagination.next` token when more pages follow: ```json theme={null} { "documents": [ { "_id": "doc-00" }, { "_id": "doc-01" }, { "_id": "doc-02" }, { "_id": "doc-03" }, { "_id": "doc-04" } ], "namespace": "articles", "pagination": { "next": "Tm90aGluZyB0byBzZWUgaGVyZQo=" }, "usage": { "read_units": 1 } } ``` ### List document IDs by prefix To limit results to documents whose IDs start with a given string, pass a `prefix`. Combined with [structured IDs](/guides/indexes/data-modeling#use-structured-ids), this lets you list every chunk of a source document: ```Python Python theme={null} # Connect to an index as shown above. for doc in index.documents.list(namespace="articles", prefix="report-2026#"): print(doc._id) ``` ```bash curl theme={null} curl "https://$INDEX_HOST/namespaces/articles/documents/list" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "prefix": "report-2026#" }' ``` The Python SDK returns a paginator, so iterating it walks every page for you. In the REST API, a response with more results to follow carries a `pagination.next` token. Pass it back as `pagination_token` to get the next page, and stop when the response has no `pagination` token. For the full request and response schema, see [List documents](/reference/api/latest/data-plane/list_documents). # Manage document chunks Source: https://docs.pinecone.io/guides/data/manage-document-chunks Fetch, search, delete, and replace all chunks of a source document in Pinecone using structured ID prefixes and a document_id metadata field. When you split a long source document into chunks, each chunk is stored as its own Pinecone document, separate from the source document it came from. To work with all of a source document's chunks at once, give each chunk a [structured ID](/guides/indexes/data-modeling#use-structured-ids) prefixed with the source document's ID, and a `document_id` metadata field. The code assumes a `chunk_text` field declared with `embed` for [integrated embedding](/guides/search/integrated-embedding), so Pinecone generates the vectors, and requires API version `2026-07` (Python SDK `10.1.0` or later). For a legacy vector index, see [Manage chunked records](/guides/legacy/vectors-api/manage-chunked-records). > [!NOTE] > > Pinecone is [eventually consistent](/guides/data/check-data-freshness), so a read right after a write (upsert, update, or delete) may not return the latest data. If you need to read immediately after writing, add a short delay or [retry logic](/guides/production/error-handling#implement-retry-logic). ## Upsert chunks [Upsert](/guides/data/upsert-data) each chunk with its structured ID and `document_id`, plus any other metadata you want to filter on or display. With integrated embedding, each upsert is capped at 96 documents instead of 1,000: ```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/indexes/target-an-index index = pc.index(host="INDEX_HOST") # Pinecone embeds `chunk_text` on write. # The other fields are stored as metadata. index.documents.upsert( namespace="example-namespace", documents=[ { "_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" }, ], ) ``` ## Search within a document To search only one source document's chunks, add a [metadata filter](/guides/search/filter-by-metadata#metadata-filter-expressions) on `document_id`. On a document index, you search with query text and Pinecone embeds it: ```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/indexes/target-an-index index = pc.index(host="INDEX_HOST") filtered_results = index.documents.search( namespace="example-namespace", top_k=3, score_by=[ {"type": "embed", "fields": ["chunk_text"], "query": "What is a vector database?"} ], filter={"document_id": {"$eq": "document1"}}, include_fields=["chunk_text"], ) for match in filtered_results.matches: print(match._id, match._score, match.chunk_text) ``` ## Fetch all chunks of a document To retrieve all of a source document's chunks, [list](/guides/data/list-record-ids) their IDs by prefix, and then [fetch](/guides/data/fetch-data) them. On a document index, you can also fetch them by passing a `filter` such as `{"document_id": {"$eq": "document1"}}` to `documents.fetch`, which returns up to 100 matches per page by default (set `limit` for up to 10,000): ```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/indexes/target-an-index index = pc.index(host="INDEX_HOST") # List all chunks for document1 using ID prefix chunk_ids = [] for doc in index.documents.list(namespace="example-namespace", prefix="document1#"): chunk_ids.append(doc._id) print(f"Found {len(chunk_ids)} chunks for document1") # Fetch the complete documents by ID if chunk_ids: response = index.documents.fetch( namespace="example-namespace", ids=chunk_ids, include_fields=["chunk_text", "chunk_number"], ) for doc_id, doc in response.documents.items(): print(f"Chunk ID: {doc_id}") print(f"Chunk text: {doc.chunk_text}") ``` ## Delete chunks To [delete](/guides/data/delete-data) some or all of a source document's chunks, filter on their 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/indexes/target-an-index index = pc.index(host="INDEX_HOST") # Delete chunks 1 and 3 index.documents.delete( namespace="example-namespace", filter={ "document_id": {"$eq": "document1"}, "chunk_number": {"$in": [1, 3]} } ) # Delete all chunks for a document index.documents.delete( namespace="example-namespace", filter={ "document_id": {"$eq": "document1"} } ) ``` ## Replace a chunked document When the number or order of a source document's chunks changes, delete all of its chunks with a metadata filter, and then upsert the new ones. To change one chunk's content without changing the chunk count, [update](/guides/data/update-data) it by ID instead. > [!TIP] > > To update most of the data in a large namespace, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) about a faster, cheaper approach based on an export. ```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/indexes/target-an-index index = pc.index(host="INDEX_HOST") # Step 1: Delete all existing chunks for the document index.documents.delete( namespace="example-namespace", filter={ "document_id": {"$eq": "document1"} } ) print("Deleted existing chunks for document1") # Step 2: Upsert the updated document chunks index.documents.upsert( namespace="example-namespace", documents=[ { "_id": "document1#chunk1", "chunk_text": "Updated first chunk with new content...", "document_id": "document1", "document_title": "Introduction to Vector Databases - Updated Edition", "chunk_number": 1, "document_url": "https://example.com/docs/document1", "created_at": "2024-02-15", "document_type": "tutorial", "version": "2.0" }, { "_id": "document1#chunk2", "chunk_text": "Updated second chunk with new content...", "document_id": "document1", "document_title": "Introduction to Vector Databases - Updated Edition", "chunk_number": 2, "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") ``` # Manage namespaces Source: https://docs.pinecone.io/guides/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 > [!NOTE] > > This feature requires the `2025-10` version of the API or later. Namespaces are created automatically as you [upsert](/guides/data/upsert-data) data. However, you can also create namespaces ahead of time using the [Create a namespace](/reference/api/latest/data-plane/createnamespace) operation. Specify a name for the namespace and, optionally, the [metadata fields to index](/guides/indexes/configure-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/indexes/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/indexes/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.MetadataFieldProperties; 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/indexes/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "INDEX_NAME"); MetadataFieldProperties filterable = MetadataFieldProperties.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/v7/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/indexes/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/indexes/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-07" \ -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 curl theme={null} { "name": "example-namespace", "record_count": "0", "size_bytes": "0", "schema": { "fields": { "document_title": { "filterable": true }, "document_url": { "filterable": true }, "chunk_number": { "filterable": true }, "document_id": { "filterable": true }, "created_at": { "filterable": true } } } } ``` > [!NOTE] > > `size_bytes` is approximate, so a value of `0` doesn't always mean the namespace is empty. Data written before size tracking reads as `0`, and recently deleted data can still be counted until compaction rewrites the underlying files. ## 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 doesn't include a `pagination_token`, there are no more namespaces to return. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.index(host="INDEX_HOST") # Implicit pagination using a generator function that yields one page at a time for page in index.list_namespaces(): for namespace in page.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/indexes/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/indexes/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(); // List all namespaces with pagination limit of 2 ListNamespacesResponse listNamespacesResponseWithLimit = index.listNamespaces(null, 2); // List all namespaces with pagination limit and token ListNamespacesResponse listNamespacesResponsePaginated = index.listNamespaces("eyJza2lwX3Bhc3QiOiIxMDEwMy0=", 5); System.out.println(listNamespacesResponseWithLimit); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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/indexes/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: 2026-07" ``` The response will look like the following: ```plaintext Python theme={null} # Implicit pagination (print output from the loop above) example-namespace : 20000 example-namespace2 : 10500 example-namespace3 : 10000 ... # Manual pagination (response from list_namespaces_paginated()) ListNamespacesResponse(namespaces=[NamespaceDescription(name='example-namespace', record_count=20000, schema=None, indexed_fields=None, size_bytes=0), NamespaceDescription(name='example-namespace2', record_count=10500, schema=None, indexed_fields=None, size_bytes=0)], pagination=Pagination(next='Tm90aGluZyB0byBzZWUgaGVyZQo='), total_count=3) ``` ```javascript JavaScript theme={null} { namespaces: [ { name: 'example-namespace', recordCount: '20000', sizeBytes: '1048576' }, { name: 'example-namespace2', recordCount: '10500', sizeBytes: '550502' }, ... ], 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", "size_bytes": "1048576" }, { "name": "example-namespace2", "record_count": "10500", "size_bytes": "550502" }, ... ], "pagination": { "next": "Tm90aGluZyB0byBzZWUgaGVyZQo=" } } ``` ## Describe a namespace Use the [Describe a 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} 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/indexes/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/v7/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/indexes/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: 2026-07" ``` 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', sizeBytes: '1048576' } ``` ```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", "size_bytes": "1048576" } ``` > [!NOTE] > > The Python, Java, and Go SDKs don't return `size_bytes` yet, so it appears in the curl and JavaScript responses only. ## Delete a namespace Use the [Delete a namespace](/reference/api/latest/data-plane/deletenamespace) operation to delete a namespace in a serverless index. > [!WARNING] > > Deleting a namespace is irreversible. All data in the namespace is permanently deleted. If a [namespace alias](/guides/data/namespace-aliases/overview) targets the namespace, the delete is rejected. Repoint or delete the alias first. ```python Python theme={null} 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/indexes/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/v7/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/indexes/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: 2026-07" ``` ## Rename a namespace Pinecone doesn't support renaming namespaces directly. Instead, you must [delete the data](/guides/data/delete-data) in the namespace and [upsert it](/guides/data/upsert-data) to a new namespace. ## Move records to a new namespace Pinecone doesn't support moving data between namespaces directly. Instead, you must [delete the data](/guides/data/delete-data) in the old namespace and [upsert it](/guides/data/upsert-data) to the new namespace. # Migrate from pgvector Source: https://docs.pinecone.io/guides/data/migrate-from-pgvector Migrate vector data from pgvector to Pinecone Database, validate search results, synchronize incremental changes, and cut over application traffic. This guide shows you how to migrate a vector-search workload from pgvector to Pinecone Database while keeping PostgreSQL available as the source of truth until cutover. It's based on the [pgvector-migration tool](https://github.com/pinecone-field/pgvector-migration), which provides a step-by-step migration manual, a runnable notebook, and a synchronization script that supports backfills, incremental synchronization, and reconciliation. > [!TIP] > > To keep your data in Postgres and search it with Pinecone instead, see [pg_pinecone](/guides/pg-pinecone/overview), an open-source Postgres extension. ## Before you migrate You need: * A Pinecone account and [API key](https://app.pinecone.io/organizations/-/projects/-/keys). * Network access to your PostgreSQL database. * Python 3.9 or later. * A PostgreSQL role that can read the tables you want to migrate. * Write access to PostgreSQL if you use the synchronization script. The script creates bookkeeping tables or an outbox table and triggers, depending on the synchronization strategy. Clone the migration repository and install its dependencies: ```bash Terminal theme={null} git clone https://github.com/pinecone-field/pgvector-migration.git cd pgvector-migration python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt ``` > [!NOTE] > > The repository's `requirements.txt` installs the `pinecone`, `psycopg`, `pgvector`, and `pyarrow` packages used throughout this guide. Set the connection string, API key, and Pinecone index name as environment variables: ```bash Terminal theme={null} export PG_CONN="postgresql://USER:PASSWORD@HOST:5432/DATABASE" export PINECONE_API_KEY="YOUR_API_KEY" export PINECONE_INDEX="pgvector-migration" ``` > [!WARNING] > > Complete the workflow first in a test or staging environment using a disposable Pinecone index and representative source data. Delete the disposable index after validation. When you repeat the workflow in production, create a new, empty production index and don't stream pilot records into its target namespaces. Bulk import requires those namespaces not to exist. > [!TIP] > > The [`migration_walkthrough.ipynb`](https://github.com/pinecone-field/pgvector-migration/blob/main/migration_walkthrough.ipynb) notebook runs every step in this guide against a local Dockerized pgvector database, so you can test the workflow before running it against your own data. ## 1. Inspect the pgvector data For every table you want to migrate, identify the primary key, vector column, vector dimension, distance metric, metadata columns, and row count. Find the vector columns and their dimensions: ```sql PostgreSQL theme={null} SELECT c.relname AS table_name, a.attname AS column_name, format_type(a.atttypid, a.atttypmod) AS column_type FROM pg_attribute a JOIN pg_class c ON c.oid = a.attrelid JOIN pg_type t ON t.oid = a.atttypid WHERE t.typname = 'vector' AND a.attnum > 0 AND NOT a.attisdropped AND c.relkind = 'r' ORDER BY table_name; ``` Inspect each pgvector index to determine the distance metric: ```sql PostgreSQL theme={null} SELECT indexname, indexdef FROM pg_indexes WHERE tablename = 'TABLE_NAME'; ``` Map the pgvector operator class to the Pinecone metric: | pgvector operator class | pgvector operator | Pinecone metric | | - | - | - | | `vector_cosine_ops` | `<=>` | `cosine` | | `vector_ip_ops` | `<#>` | `dotproduct` | | `vector_l2_ops` | `<->` | `euclidean` | If the table doesn't have a pgvector index, inspect the distance operator used by your application queries. The Pinecone index dimension and metric must match the source data. Also record the source count for each table. You'll compare these counts with Pinecone after the backfill: ```sql PostgreSQL theme={null} SELECT count(*) FROM TABLE_NAME; ``` ## 2. Map access controls If your tables use PostgreSQL row-level security (RLS), review every policy before choosing a Pinecone layout: ```sql PostgreSQL theme={null} SELECT schemaname, tablename, policyname, cmd, qual FROM pg_policies WHERE schemaname = 'public' ORDER BY tablename, policyname; ``` Pinecone doesn't evaluate PostgreSQL RLS policies. Use a namespace for a hard tenant boundary, or copy access-control attributes into record metadata and apply a server-side metadata filter to every search. Derive the namespace or filter values from the authenticated session, not from client input. If a policy depends on joins, functions, or data outside the vector row, enforce the access decision in your application. When you denormalize permissions into metadata, synchronize permission changes as well as changes to the vector table. ## 3. Choose the index and namespace layout By default, `sync.py` uses one Pinecone index and maps each PostgreSQL table to a namespace with the same name. The steps below use this layout. Tables can share an index only when their vectors have the same dimension and use the same distance metric. | Source data | Pinecone layout | | - | - | | One table, or several tables searched independently | One namespace per table in a shared index | | Several tables searched together | One shared namespace with a `source_table` metadata field | | Tables with different dimensions or metrics | One index per dimension and metric combination | | Tenant-isolated data | One namespace per tenant, with optional metadata filters for finer access control | To use a shared namespace, tenant-based namespaces, or multiple indexes, update the namespace and index routing in `sync.py` before you run the migration. Use a string for every record ID. The migration repository prefixes source IDs with the table name, such as `documents#4021`, to prevent collisions. Each Pinecone record contains the vector in `values` and selected source columns in `metadata`. Metadata values must be strings, numbers, booleans, or lists of strings. Omit `NULL` values and convert PostgreSQL `numeric` values to floats. Don't name a source metadata field `metadata`; `metadata` is the top-level Parquet column that contains the JSON-encoded metadata object. ## 4. Create the Pinecone index > [!NOTE] > > The examples below use two PostgreSQL tables, `documents` and `products`, with 768-dimensional vectors stored in an `embedding` column and queried using cosine distance. Replace all example table names, column names, dimensions, metrics, metadata fields, and namespaces with values from your workload. Create a new, empty production serverless index with the dimension and metric you identified from pgvector: ```python Python theme={null} import os from pinecone import Pinecone, ServerlessSpec pc = Pinecone( api_key=os.environ["PINECONE_API_KEY"], source_tag="pinecone_io:docs:pgvector_migration", ) index_name = "pgvector-migration" if not pc.has_index(index_name): pc.create_index( name=index_name, dimension=768, metric="cosine", spec=ServerlessSpec(cloud="aws", region="us-east-1"), ) ``` Replace the example dimension, metric, cloud, and region with values appropriate for your workload. If separate source tables have different dimensions or metrics, create separate indexes. ## 5. Configure the source tables In the cloned migration repository, edit the `TABLES` configuration near the top of [`sync.py`](https://github.com/pinecone-field/pgvector-migration/blob/main/sync.py) to match your PostgreSQL schema. Each entry defines the primary key, vector column, metadata columns, and optional change timestamp: ```python Python theme={null} TABLES = { "documents": { "id": "id", "vector": "embedding", "metadata": ["title", "category"], "updated_at": "updated_at", }, "products": { "id": "id", "vector": "embedding", "metadata": ["name", "price"], "updated_at": "updated_at", }, } ``` By default, `sync.py` maps each configured table to a namespace with the same name. Run all `sync.py` commands below from the root of the cloned pgvector-migration repository. ## 6. Backfill the records ### Initialize change tracking The following workflow uses the default change-log strategy. If the source stays writable during the backfill, initialize change tracking before copying records. This captures changes made during the backfill so you can apply them afterward: ```bash Terminal theme={null} python sync.py init --strategy changelog ``` ### Bulk import For a production backfill, use [bulk import](/guides/data/import-data). Create an `export.py` file with the following code from the tool's migration workflow. It writes one import-ready Parquet file per table. > [!NOTE] > > The export script reuses the PostgreSQL connection, `TABLES` configuration, and record-mapping helpers from `sync.py`. Configure `TABLES` in `sync.py` before running the export. ```python Python theme={null} import json import os import pyarrow as pa import pyarrow.parquet as pq from sync import TABLES, build_record, connect, select_cols PARQUET_SCHEMA = pa.schema([ ("id", pa.string()), ("values", pa.list_(pa.float32())), ("metadata", pa.string()), ]) def export_table_to_parquet(conn, table, config, output_path): ids, values, metadata = [], [], [] with conn.transaction(): with conn.cursor(name=f"stream_{table}") as cursor: cursor.execute(f"SELECT {select_cols(config)} FROM {table}") for row in cursor: record_id, vector, record_metadata = build_record( table, row, config ) ids.append(record_id) values.append(vector) metadata.append(json.dumps(record_metadata)) arrow_table = pa.table( {"id": ids, "values": values, "metadata": metadata}, schema=PARQUET_SCHEMA, ) pq.write_table(arrow_table, output_path) print(f"Wrote {len(ids)} records to {output_path}") conn = connect() try: os.makedirs("export", exist_ok=True) for table, config in TABLES.items(): os.makedirs(f"export/{table}", exist_ok=True) export_table_to_parquet( conn, table, config, f"export/{table}/0.parquet", ) finally: conn.close() ``` Run the export: ```bash Terminal theme={null} python export.py ``` The script creates one directory per namespace and one Parquet file per table: ```console Output theme={null} export/ ├── documents/ │ └── 0.parquet └── products/ └── 0.parquet ``` If a table would produce a file larger than the maximum file size, split it into numbered files in the same namespace directory. Review the [import limits](/guides/data/import-data#import-limits) before exporting a large dataset. Upload the generated directory tree to Amazon S3, Google Cloud Storage, or Azure Blob Storage. Then start an import using the import root URI: ```python Python theme={null} from pinecone import ImportErrorMode index = pc.index(host="INDEX_HOST") operation = index.start_import( uri="s3://BUCKET_NAME/IMPORT_ROOT", integration_id="STORAGE_INTEGRATION_ID", error_mode=ImportErrorMode.CONTINUE, ) print(operation.id) ``` Use the import ID with the [`describe_import` operation](/guides/data/import-data#5-track-import-progress) to monitor progress. Each import takes at least 10 minutes. Wait until the import status is `Completed` before validating record counts in the next step. The target namespaces must not already exist. A private bucket or container requires a [storage integration](/guides/storage-integrations/manage-storage-integrations). ### Streaming backfill For a small dataset, you can instead use the streaming backfill in `sync.py`: ```bash Terminal theme={null} python sync.py backfill ``` Streaming upsert requests are limited by both record count and request size. The script uses batches of 200 records to stay below the 2 MB request limit for its 768-dimensional example. Reduce the batch size for larger vectors or metadata. ### Apply captured changes If you initialized change tracking, apply the changes captured while the backfill was running: ```bash Terminal theme={null} python sync.py sync --strategy changelog ``` ## 7. Validate the backfill Compare the source row count for each table with the record count for its target namespace: ```python Python theme={null} index = pc.index(host="INDEX_HOST") stats = index.describe_index_stats() print(stats.total_vector_count) for namespace, details in stats.namespaces.items(): print(namespace, details.vector_count) ``` Index statistics are eventually consistent, so allow time for the counts to update. Next, run a representative set of query vectors against pgvector and Pinecone. For example, the following code compares the top 10 results for a vector selected from the `documents` table: ```python Python theme={null} import os import psycopg from pgvector.psycopg import register_vector from pinecone import Pinecone conn = psycopg.connect(os.environ["PG_CONN"]) register_vector(conn) pc = Pinecone( api_key=os.environ["PINECONE_API_KEY"], source_tag="pinecone_io:docs:pgvector_migration", ) index = pc.index(host="INDEX_HOST") query_vector = conn.execute( "SELECT embedding FROM documents WHERE embedding IS NOT NULL LIMIT 1" ).fetchone()[0] pgvector_ids = [ f"documents#{row[0]}" for row in conn.execute( "SELECT id FROM documents ORDER BY embedding <=> %s LIMIT %s", (query_vector, 10), ).fetchall() ] pinecone_ids = [ match.id for match in index.query( vector=query_vector.tolist(), top_k=10, namespace="documents", ).matches ] print("pgvector:", pgvector_ids) print("Pinecone:", pinecone_ids) ``` Replace the table, columns, namespace, and pgvector operator with values for your workload. Use `<=>` for cosine distance, `<#>` for inner product, or `<->` for Euclidean distance. Compare the returned record IDs and ordering. Small ordering differences for near-ties are expected with approximate search. Large differences can indicate a mismatched metric or inconsistent vector normalization. ## 8. Keep Pinecone synchronized After the initial copy, synchronize inserts, updates, and deletes until cutover. The repository's `sync.py` supports two strategies: | Strategy | Use when | Behavior | | - | - | - | | Change-log | Updates and deletes must be captured reliably. | Creates an outbox table and per-table triggers, then applies the latest operation for each record. | | Watermark | The workload is mostly inserts and has a maintained `updated_at` column. | Tracks migrated IDs and the last synchronization timestamp. Deletes are detected with an anti-join. | The change-log strategy is the default. Run the synchronization command on a schedule until cutover: ```bash Terminal theme={null} python sync.py sync --strategy changelog ``` The PostgreSQL role used by the script must be able to create the outbox table, functions, and triggers, and update the outbox table. For workloads that are mostly inserts and have a maintained `updated_at` column, the tool also supports a watermark strategy. This strategy uses its first synchronization run to backfill records. For setup, limitations, and commands, see the [watermark strategy in the pgvector-migration tool](https://github.com/pinecone-field/pgvector-migration#strategy-a--watermark--anti-join-in-postgres-simplest). Periodically reconcile all record IDs, and run reconciliation immediately before cutover: ```bash Terminal theme={null} python sync.py reconcile ``` Reconciliation upserts records missing from Pinecone and deletes records that no longer exist in pgvector. ## 9. Cut over application traffic Keep pgvector serving traffic and continue synchronization while you cut over: 1. Shadow a sample of production searches to Pinecone without returning those results to users. Compare search quality and latency. 2. Route a small percentage of reads to Pinecone and monitor results. 3. Increase the percentage after validation. 4. Immediately before switching the primary read path, run `sync` with your selected strategy, run `python sync.py reconcile`, and then run `sync` again to apply changes captured during reconciliation. 5. Run `sync` once more and confirm that it reports no outstanding changes. Then make Pinecone the primary read path. 6. Keep pgvector available as a rollback target until the new read path is stable. You can point reads back to pgvector as it never stopped serving and is still authoritative. For implementation details, troubleshooting, and the complete runnable workflow, see the [pgvector-migration tool](https://github.com/pinecone-field/pgvector-migration). # Manage namespace aliases Source: https://docs.pinecone.io/guides/data/namespace-aliases/manage-aliases Create, list, describe, repoint, and delete namespace aliases in a Pinecone index with the REST API or the Pinecone console. > [!NOTE] > > Creating and managing aliases requires API version `2026-07` or later and is available through the REST API and the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes). Reading through an alias works on any API version, including the current SDKs. Create, list, describe, repoint, and delete [namespace aliases](/guides/data/namespace-aliases/overview) in an index. Each operation is a single REST call to your [index host](/guides/indexes/target-an-index). To swap the data an application reads with no downtime, see [Swap a namespace](/guides/data/namespace-aliases/swap-a-namespace). You need a [project role](/admin/security/manage-rbac#common-role-assignments) that can manage namespaces, such as `DataPlaneEditor`, `ProjectOwner`, or `ProjectManager`. ## Operations | Action | Operation | | :- | :- | | Create an alias | `POST /namespace-aliases` with `{"name", "target_namespace"}` | | List aliases in the index | `GET /namespace-aliases` | | Describe one alias | `GET /namespace-aliases/{alias_name}` | | Repoint an alias | `PATCH /namespace-aliases/{alias_name}` with `{"target_namespace"}` | | Delete an alias | `DELETE /namespace-aliases/{alias_name}` | Each alias is returned as `{name, target_namespace, created_at, updated_at}`. `updated_at` advances on every repoint. You can also manage aliases in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes). Open the index, go to the **Namespaces** tab, and click **Manage aliases** to create, repoint, or delete an alias. ## Errors Every rejection carries a machine-readable reason in `details[0].reason`. SDKs and agents branch on the reason, not the message text. | Reason | When | | :- | :- | | `ALIAS_NAME_INVALID` | The alias name breaks the naming rules. | | `ALIAS_ALREADY_EXISTS` | An alias with this name exists. `details[0].metadata.target_namespace` is its current target. | | `NAME_IN_USE_BY_NAMESPACE` | The name is taken by a namespace. | | `TARGET_NAMESPACE_NOT_FOUND` | The target namespace doesn't exist. | | `TARGET_NAMESPACE_NOT_ACTIVE` | The target namespace is still initializing, importing, or restoring. The same request works once it's active. | | `TARGET_IS_ALIAS` | The target is an alias. Aliases can't chain. | | `ALIASES_PER_INDEX_EXCEEDED` | The index has 1,000 aliases already. | | `ALIAS_NOT_FOUND` | Describe, repoint, or delete on a name that isn't an alias. | You also get a reason when a request addresses an alias name where it shouldn't: | Reason | When | | :- | :- | | `NAME_IN_USE_BY_ALIAS` | An upsert addressed an alias name. Write to the target namespace instead. | | `WRITE_TO_ALIAS` | An update or delete addressed an alias name. Same fix. | | `NAMESPACE_OPERATION_ON_ALIAS` | A namespace describe or delete addressed an alias name. Use the alias endpoints. | | `NAMESPACE_TARGETED_BY_ALIAS` | A namespace delete while an alias still points at it. Repoint or delete the alias first. | ## Create an alias Specify a `name` for the alias and the `target_namespace` it points at. The target must be an existing, ready namespace in the same index. A namespace that's still initializing, importing, or restoring is refused. If a create returns a 409 with reason `ALIAS_ALREADY_EXISTS` and `details[0].metadata.target_namespace` matches the target you asked for, an earlier call already succeeded and the alias is live, so a retry can treat it as done. A different target is a real conflict. ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/namespace-aliases" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "name": "example-alias", "target_namespace": "example-namespace-v1" }' ``` ## List aliases List the aliases in an index to see what each one targets. ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/namespace-aliases" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" ``` The response lists the aliases in the index, ordered by name, with a `total_count`. When more aliases remain, the response includes a `pagination.next` token. Pass it as `paginationToken` on the next request to get the following page. Use `limit` to set the page size, and filter the list by `prefix` and `target_namespace`. ```json curl theme={null} { "namespace_aliases": [ { "name": "example-alias", "target_namespace": "example-namespace-v1", "created_at": "2026-09-01T12:00:00Z", "updated_at": "2026-09-01T12:00:00Z" } ], "total_count": 1 } ``` ## Describe an alias Describe a single alias to see its current target and when it last changed. ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/namespace-aliases/example-alias" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" ``` Create, describe, and repoint return the alias object: ```json curl theme={null} { "name": "example-alias", "target_namespace": "example-namespace-v1", "created_at": "2026-09-01T12:00:00Z", "updated_at": "2026-09-01T12:00:00Z" } ``` ## Repoint an alias Point the alias at a different namespace. The repoint is atomic, and when the call returns success, all reads resolve to the new target. Repointing to a namespace that doesn't exist or isn't ready is rejected, and the alias keeps its current target. ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X PATCH "https://$INDEX_HOST/namespace-aliases/example-alias" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "target_namespace": "example-namespace-v2" }' ``` ## Delete an alias Deleting an alias never touches the target namespace or its data. A delete that returns a 404 means the alias is already gone, so a retry can safely treat it as done. > [!WARNING] > > Any application still reading through the alias name will start getting empty results, not an error. Move your readers to the namespace name, or to a different alias, before you delete. ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X DELETE "https://$INDEX_HOST/namespace-aliases/example-alias" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" ``` ## See also * [Namespace aliases overview](/guides/data/namespace-aliases/overview) * [Swap a namespace](/guides/data/namespace-aliases/swap-a-namespace) # Namespace aliases overview Source: https://docs.pinecone.io/guides/data/namespace-aliases/overview A namespace alias is a stable name for a namespace that you can repoint at any time, switching the data your application reads without a code change or redeploy. > [!NOTE] > > Creating and managing aliases requires API version `2026-07` or later and is available through the REST API and the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes). Reading through an alias works on any API version, including the current SDKs. A **namespace alias** is a stable, repointable name inside an index that points at a [namespace](/guides/indexes/index-data-overview#namespaces). An alias holds no data of its own. It's a pointer. Your application reads through the alias name, and you can atomically repoint the alias to a different namespace in the same index at any time, with no application config change and no redeploy. Without an alias, changing what data an application reads means loading it into a new namespace, then editing the namespace name in your application and redeploying. With an alias, you point your application at the alias once, and every later cutover is a single API call. Writes (upsert, update, and delete) always address a namespace name directly, never the alias, so your ingest target and your live read target stay separate during a cutover. To put an alias to work, see [Swap a namespace](/guides/data/namespace-aliases/swap-a-namespace) and [Manage aliases](/guides/data/namespace-aliases/manage-aliases). ## How aliases work An alias lives on the [index host](/guides/indexes/target-an-index), scoped to a single index alongside the namespaces it can point to, so alias operations use the same host as your namespace and data operations. You can pass an alias name wherever a read request takes a namespace name (the `namespace` field in the body, the `namespace` query parameter, or the `{namespace}` path segment), and Pinecone resolves it to the target namespace server-side. Resolution covers every read endpoint: query, vector fetch, fetch by metadata, and list; record search; and document search, fetch, and list. Everything else addresses the namespace directly. Writes (upsert, update, and delete) sent to an alias name are rejected, and so are namespace operations like describing or deleting a namespace. An alias is a separate resource with its own endpoints under `/namespace-aliases`, so you never manage a namespace through its alias, or an alias through the namespace endpoints. In each case the error names the alias and the namespace it points at, so you know to send the request to the namespace directly. An alias name must be unique within the index and can't match a namespace name. Because the name appears in the request path, it also has to be URL-safe: ASCII graphic characters, no spaces or `/ ? # % & = \ ; +`, with `.`, `..`, and `__default__` reserved. An alias name can be up to 512 characters, the same limit as a namespace. So the two match on length, but an alias is stricter on allowed characters, since a namespace accepts almost any ASCII. An omitted or empty target is rejected, and an alias is ready the moment you create it, with no provisioning step to wait on. ## What aliases guarantee * Writes always address a namespace directly, so your ingest target and live read target never blur. * You can't delete a namespace while an alias points to it, and a failed repoint leaves the alias on its current target. * Within an index, a name is either a namespace or an alias, never both. * Reads report the namespace that served them, so you can confirm what an alias resolved to. ## Limits * An alias can only target a namespace in the same index, so it shares the index's dimension and metric. * An index can have up to 1,000 aliases. * An alias is metadata only, so it costs nothing to keep. Reads through an alias bill as reads of the target namespace. * Aliases are a separate resource from namespaces. They don't appear in namespace listings (`GET /namespaces`) or in `describe_index_stats`; list them with `GET /namespace-aliases`. * Deleting an alias makes reads through that name return empty results, not an error, so move readers to a live name before you delete. * Restoring an index from a backup creates a new index, so the original's aliases don't carry over. * You manage aliases through the REST API or the Pinecone console, and reads through an alias work in the SDKs. * Alias changes aren't in the audit log export. ## See also * [Swap a namespace](/guides/data/namespace-aliases/swap-a-namespace) * [Manage aliases](/guides/data/namespace-aliases/manage-aliases) * [Manage namespaces](/guides/data/manage-namespaces) # Swap a namespace without downtime Source: https://docs.pinecone.io/guides/data/namespace-aliases/swap-a-namespace Refresh the data behind a namespace alias with no downtime: create an alias, ingest a new namespace, then atomically repoint reads to it. > [!NOTE] > > Creating and managing aliases requires API version `2026-07` or later and is available through the REST API and the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes). Reading through an alias works on any API version, including the current SDKs. The primary use case for a [namespace alias](/guides/data/namespace-aliases/overview) is swapping the data an application reads without a redeploy: re-ingest into a new namespace, validate it, then flip live reads to it in one call. This guide refreshes the data behind an alias named `example-alias`, moving it from `example-namespace-v1` to `example-namespace-v2` with no downtime. The examples use the vector API; the same alias substitution works on any read endpoint. ## Before you begin Ensure you have the following: * An existing index containing the namespace serving live traffic. * A [project role](/admin/security/manage-rbac#common-role-assignments) that can manage namespaces, such as `DataPlaneEditor`, `ProjectOwner`, or `ProjectManager`. ## Swap the namespace **1. Create an alias** Create an alias pointing at the namespace serving live traffic. Specify a `name` for the alias and the `target_namespace` it points at. ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/namespace-aliases" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "name": "example-alias", "target_namespace": "example-namespace-v1" }' ``` The response returns the alias: ```json curl theme={null} { "name": "example-alias", "target_namespace": "example-namespace-v1", "created_at": "2026-09-01T12:00:00Z", "updated_at": "2026-09-01T12:00:00Z" } ``` **2. Read through the alias** Point your application's reads at the alias name. Pass it wherever you'd pass a namespace name; here, that's the `namespace` field in a query request. ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" # Stand-in built with jq. Replace with your query embedding, which must match the index's dimension (1536 in this example) QUERY_VECTOR=$(jq -nc '[range(1536) | 0.1]') curl "https://$INDEX_HOST/query" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "namespace": "example-alias", "vector": '"$QUERY_VECTOR"', "topK": 3, "includeMetadata": true }' ``` The response's `namespace` field reports the namespace that served the read. You sent `example-alias`, and the read came back from `example-namespace-v1`, so you can verify what the alias points at from the read itself. **3. Ingest the new data** Ingest the refreshed data into a new namespace. Writes never use the alias, so live read traffic keeps landing on `example-namespace-v1` while you build `example-namespace-v2`. ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" # Stand-in built with jq. Replace with your record's embedding, which must match the index's dimension (1536 in this example) VECTOR=$(jq -nc '[range(1536) | 0.1]') curl "https://$INDEX_HOST/vectors/upsert" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "namespace": "example-namespace-v2", "vectors": [ { "id": "vec1", "values": '"$VECTOR"' } ] }' ``` Validate `example-namespace-v2` by reading it directly by its own name. **4. Cut over in one call** Repoint the alias to the new namespace. The repoint is atomic (all or nothing, no partial state), and when the call returns success, all reads resolve to the new target. > [!NOTE] > > A paginated read (a list, or a filtered fetch) that's already in progress when you repoint finishes its remaining pages against the new target. ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X PATCH "https://$INDEX_HOST/namespace-aliases/example-alias" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "target_namespace": "example-namespace-v2" }' ``` **5. Verify the cutover** Describe the alias to confirm the current target and the last repoint time: ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/namespace-aliases/example-alias" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" ``` The `target_namespace` now reads `example-namespace-v2`, and `updated_at` has advanced to the repoint time: ```json curl theme={null} { "name": "example-alias", "target_namespace": "example-namespace-v2", "created_at": "2026-09-01T12:00:00Z", "updated_at": "2026-09-01T12:30:00Z" } ``` **6. Retire the old namespace** When you're ready, [delete](/guides/data/manage-namespaces#delete-a-namespace) the old `example-namespace-v1` namespace. The delete succeeds now that no alias targets it. Before the repoint, the delete would have been rejected because the alias still pointed at it. ## See also * [Namespace aliases overview](/guides/data/namespace-aliases/overview) * [Manage aliases](/guides/data/namespace-aliases/manage-aliases) # Update data Source: https://docs.pinecone.io/guides/data/update-data Patch fields on Pinecone documents by ID, or update metadata fields across every document in a document index that matches a filter. This page shows you how to update documents in a [namespace](/guides/indexes/index-data-overview#namespaces) of a document index. You can patch fields on a document by ID, or patch metadata fields across every document matching a filter. To replace whole documents, use the [upsert](/guides/data/upsert-data) operation instead. For a legacy vector index, see [Update vectors](/guides/legacy/vectors-api/update-vectors). > [!TIP] > > Updates consume [write units (WUs)](/guides/cost/understand-cost#write-units). See [Understand Pinecone cost](/guides/cost/understand-cost#update) for how update cost is calculated. ## Update documents In an index with a document schema, [upsert](/guides/data/upsert-data#upsert-documents) replaces the whole document for a given `_id`. To change individual fields instead, use the documents update operation, which leaves the fields you don't mention unchanged. To patch specific documents, send one entry per `_id`. Include the fields you want to set, and name any fields to drop in `_remove_fields`. Both schema-declared fields and metadata fields can be set or removed this way: ```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/indexes/target-an-index index = pc.index(host="INDEX_HOST") index.documents.update( namespace="articles", documents=[ {"_id": "doc1", "body": "Updated body text."}, # schema-declared field {"_id": "doc2", "_remove_fields": ["author"]}, # metadata field ], ) ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/namespaces/articles/documents/update" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "documents": [ { "_id": "doc1", "body": "Updated body text." }, { "_id": "doc2", "_remove_fields": ["author"] } ] }' ``` To apply the same patch to every document matching a [metadata filter expression](/guides/indexes/index-data-overview#metadata-filter-expressions), send `filter` with `set_fields`, `remove_fields`, or both: ```Python Python theme={null} # Connect to an index as shown above. index.documents.update( namespace="articles", filter={"category": {"$eq": "news"}}, set_fields={"status": "archived"}, remove_fields=["author"], ) ``` ```bash curl theme={null} curl "https://$INDEX_HOST/namespaces/articles/documents/update" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "filter": { "category": { "$eq": "news" } }, "set_fields": { "status": "archived" }, "remove_fields": ["author"] }' ``` The response reports how many documents matched the filter: ```json theme={null} { "matched_records": 2 } ``` For the full request and response schema, see [Update documents](/reference/api/latest/data-plane/update_documents). ### Limitations * **By-ID requests**: Each request can patch up to 1,000 documents, or 96 when the schema declares `embed` or `sparse_embed` (even a metadata-only patch). See [Update limits](/reference/api/database-limits/operation-limits#update-limits). * **By-filter requests**: `set_fields` and `remove_fields` both accept metadata fields only, and reject a field declared in the schema with a `400`. A by-filter update applies one value to every matched document, which would leave vector and full-text-searchable fields identical across the whole match set. To change a schema-declared field, patch each document by ID. * **Text-match filters**: A by-filter update rejects [text-match operators](/guides/search/filter-by-metadata#text-match-filters) (`$match_phrase`, `$match_all`, `$match_any`) with a `400`. To update documents by text match, [search](/guides/search/full-text-search) for them first and patch the IDs the search returns. > [!WARNING] > > This operation ignores the `dry_run` parameter that [Update by metadata](/guides/legacy/vectors-api/update-vectors#update-by-metadata) on the legacy Vectors API supports. A `dry_run` request returns `202` with a `matched_records` count and applies the update anyway. It also accepts unrecognized parameters rather than rejecting them, so check the parameter names before you send a request you can't undo. ## 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/data/check-data-freshness#check-the-log-sequence-number) to check whether an update request has completed. ## See also * [Replace a chunked document](/guides/data/manage-document-chunks#replace-a-chunked-document) # Upsert data Source: https://docs.pinecone.io/guides/data/upsert-data Upsert documents into a Pinecone document index, batch upserts for higher throughput, and partition data with namespaces. This page shows you how to upsert documents into a namespace in a document index. [Namespaces](/guides/indexes/index-data-overview#namespaces) let you partition data within an index and are essential for [implementing multitenancy](/guides/data/implement-multitenancy) when you need to isolate the data of each customer or user. If an ID already exists, upserting overwrites the entire document. To change only part of a document, [update](/guides/data/update-data) it. For a legacy vector index, see [Upsert vectors](/guides/legacy/vectors-api/upsert-vectors). For a legacy integrated index, see [Upsert text](/guides/legacy/records-api/upsert-text). > [!TIP] > > Upserts consume [write units (WUs)](/guides/cost/understand-cost#write-units). See [Understand Pinecone cost](/guides/cost/understand-cost#upsert) for how upsert cost is calculated. To control costs when ingesting large datasets (10,000,000+ documents), use [import](/guides/data/import-data) instead of upsert. ## Upsert documents [Documents](/guides/get-started/key-terms#document) are the unit of data in a document index. 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 with the `full_text_search` config, and a separate `dense_vector` field can store vector values you provide at upsert time. A `string` field can also declare `embed` or `sparse_embed` so Pinecone embeds its text with [integrated embedding](/guides/search/integrated-embedding). The following example upserts two documents into the `articles` namespace with the [Documents API](/guides/get-started/documents-api). Each document is indexed for BM25 ranking on `body`. The `category` field isn't declared in the schema, so it's stored as metadata and automatically indexed for filtering: ```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/indexes/target-an-index index = pc.index(host="INDEX_HOST") index.documents.upsert( namespace="articles", 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", }, ], ) ``` ```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/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST', namespace: 'articles' }); await index.documents.upsert({ 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', }, ], }); ``` ```go Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v7/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/indexes/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "articles"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } _, err = idxConnection.UpsertDocuments(ctx, &pinecone.UpsertDocumentsRequest{ Documents: []pinecone.Document{ { "_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", }, }, }) if err != nil { log.Fatalf("Failed to upsert documents: %v", err) } } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/namespaces/articles/documents/upsert" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -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" } ] }' ``` > [!NOTE] > > The Documents API requires API version `2026-07` or later. The schema declares only ranking fields: `string` fields with `full_text_search`, `embed`, or `sparse_embed`, plus `dense_vector` and `sparse_vector` fields. Any other field you upsert is stored on the document as metadata, returned with `include_fields`, and indexed for filtering. Field names must be unique, non-empty strings of up to 64 bytes. They can't start with `_`, which is reserved for system fields such as `_id` and `_score`, or with `$`, which is reserved for filter operators. Upsert replaces the whole document for a given `_id`. To change individual fields, see [Update documents](/guides/data/update-data#update-documents). For document, field, and request size limits, see [Upsert limits](/reference/api/database-limits/operation-limits#upsert-limits). For more examples and the response schema, see [Full-text search](/guides/search/full-text-search). ## Upsert dense vectors To upsert dense vectors into a [document index](/guides/indexes/create-an-index#create-a-document-index), use the [Upsert documents](/reference/api/latest/data-plane/upsert_documents) operation: * Specify the [`namespace`](/guides/indexes/index-data-overview#namespaces) to upsert into. If the namespace doesn't exist, it's created. To use the default namespace, set the namespace to `"__default__"`. * Format your input data as documents, each with the following: * An `_id` field with a unique document identifier for the index namespace. * The `dense_vector` field declared in the index schema, with the vector values. This example uses a field named `embedding`. * Optionally, other fields, which are stored as [metadata](/guides/indexes/index-data-overview#metadata). When you search the index, you can use metadata to [filter search results](/guides/search/filter-by-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/indexes/target-an-index index = pc.index(host="INDEX_HOST") index.documents.upsert( namespace="example-namespace", documents=[ { "_id": "A", "embedding": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1], "genre": "comedy", "year": 2020 }, { "_id": "B", "embedding": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2], "genre": "documentary", "year": 2019 }, { "_id": "C", "embedding": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3], "genre": "comedy", "year": 2019 }, { "_id": "D", "embedding": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4], "genre": "drama" }, ], ) ``` ```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/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST', namespace: 'example-namespace' }); await index.documents.upsert({ documents: [ { _id: 'A', embedding: [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1], genre: "comedy", year: 2020 }, { _id: 'B', embedding: [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2], genre: "documentary", year: 2019 }, { _id: 'C', embedding: [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3], genre: "comedy", year: 2019 }, { _id: 'D', embedding: [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4], genre: "drama" }, ], }); ``` ```go Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v7/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/indexes/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.UpsertDocuments(ctx, &pinecone.UpsertDocumentsRequest{ Documents: []pinecone.Document{ { "_id": "A", "embedding": []float32{0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1}, "genre": "comedy", "year": 2020, }, { "_id": "B", "embedding": []float32{0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2}, "genre": "documentary", "year": 2019, }, { "_id": "C", "embedding": []float32{0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3}, "genre": "comedy", "year": 2019, }, { "_id": "D", "embedding": []float32{0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4}, "genre": "drama", }, }, }) if err != nil { log.Fatalf("Failed to upsert documents: %v", err) } } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/namespaces/example-namespace/documents/upsert" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "documents": [ { "_id": "A", "embedding": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1], "genre": "comedy", "year": 2020 }, { "_id": "B", "embedding": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2], "genre": "documentary", "year": 2019 }, { "_id": "C", "embedding": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3], "genre": "comedy", "year": 2019 }, { "_id": "D", "embedding": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4], "genre": "drama" } ] }' ``` ## Upsert sparse vectors Upsert sparse vectors when your data is encoded by a learned sparse model, such as [`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0), or when your application generates the sparse vectors itself. For BM25 keyword search over raw text without managing a model, see [Upsert documents](#upsert-documents). To upsert sparse vectors into a [document index](/guides/indexes/create-an-index#create-a-document-index), use the [Upsert documents](/reference/api/latest/data-plane/upsert_documents) operation: * Specify the [`namespace`](/guides/indexes/index-data-overview#namespaces) to upsert into. If the namespace doesn't exist, it's created. To use the default namespace, set the namespace to `"__default__"`. * Format your input data as documents, each with the following: * An `_id` field with a unique document identifier for the index namespace. * The `sparse_vector` field declared in the index schema, with `indices` and `values` arrays. This example uses a field named `sparse_embedding`. * Optionally, other fields, which are stored as [metadata](/guides/indexes/index-data-overview#metadata). When you search 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 pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/target-an-index index = pc.index(host="INDEX_HOST") index.documents.upsert( namespace="example-namespace", documents=[ { "_id": "vec1", "sparse_embedding": { "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] }, "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_embedding": { "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] }, "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_embedding": { "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] }, "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_embedding": { "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] }, "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/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST', namespace: 'example-namespace' }); await index.documents.upsert({ documents: [ { _id: 'vec1', sparse_embedding: { 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], }, 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_embedding: { 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], }, 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_embedding: { 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], }, 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_embedding: { 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], }, chunk_text: "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.", category: 'technology', quarter: 'Q4', }, ], }); ``` ```go Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v7/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/indexes/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.UpsertDocuments(ctx, &pinecone.UpsertDocumentsRequest{ Documents: []pinecone.Document{ { "_id": "vec1", "sparse_embedding": map[string]interface{}{ "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}, }, "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_embedding": map[string]interface{}{ "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.5605469}, }, "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_embedding": map[string]interface{}{ "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}, }, "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_embedding": map[string]interface{}{ "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}, }, "chunk_text": "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.", "category": "technology", "quarter": "Q4", }, }, }) if err != nil { log.Fatalf("Failed to upsert documents: %v", err) } } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/namespaces/example-namespace/documents/upsert" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "documents": [ { "_id": "vec1", "sparse_embedding": { "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] }, "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_embedding": { "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] }, "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_embedding": { "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] }, "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_embedding": { "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] }, "chunk_text": "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.", "category": "technology", "quarter": "Q4" } ] }' ``` ## Upsert in batches > [!TIP] > > To control costs when ingesting large datasets (10,000,000+ records), use [import](/guides/data/import-data) instead of upsert. Send upserts in batches to help increase throughput. A request can contain up to 1,000 documents and 2 MB, or up to 96 documents when the schema declares `embed` or `sparse_embed`. The lower limit comes from the [hosted embedding models](/guides/indexes/index-configuration#embedding-models) used during integrated embedding. In Python, `index.documents.batch_upsert` splits a larger list into batches, sends them in parallel, and halves any batch the server rejects as too large. ```python Python theme={null} import random 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/indexes/target-an-index index = pc.index(host="INDEX_HOST") # Example data: 10,000 documents with a 128-dimension `embedding` field documents = [ {"_id": f"doc-{i}", "embedding": [random.random() for _ in range(128)]} for i in range(10000) ] # Upsert 200 documents per request result = index.documents.batch_upsert( namespace="example-namespace", documents=documents, batch_size=200, ) print(result) ``` ```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/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST', namespace: 'example-namespace' }); // Example data: 10,000 documents with a 128-dimension `embedding` field const documents = Array.from({ length: 10000 }, (_, i) => ({ _id: `doc-${i}`, embedding: Array.from({ length: 128 }, () => Math.random()), })); // Upsert 200 documents per request for (let i = 0; i < documents.length; i += 200) { await index.documents.upsert({ documents: documents.slice(i, i + 200) }); } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "math/rand" "github.com/pinecone-io/go-pinecone/v7/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/indexes/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) } // Example data: 10,000 documents with a 128-dimension `embedding` field documents := make([]pinecone.Document, 10000) for i := range documents { embedding := make([]float32, 128) for j := range embedding { embedding[j] = rand.Float32() } documents[i] = pinecone.Document{"_id": fmt.Sprintf("doc-%d", i), "embedding": embedding} } // Upsert 200 documents per request batchSize := 200 for start := 0; start < len(documents); start += batchSize { end := min(start+batchSize, len(documents)) _, err := idxConnection.UpsertDocuments(ctx, &pinecone.UpsertDocumentsRequest{Documents: documents[start:end]}) if err != nil { log.Fatalf("Failed to upsert batch starting at %d: %v", start, err) } } } ``` ## Upsert in parallel > [!TIP] > > Python SDK v6.0.0 and later provide `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). Asyncio support lets you use Pinecone with async web frameworks such as FastAPI, Quart, and Sanic. For details, see [Async requests](/reference/sdks/python/overview#async-requests). Send multiple upserts in parallel to help increase throughput. Each upsert call blocks until the response arrives, so send several at once. In Python, `batch_upsert` sends batches in parallel. Set `max_concurrency` to cap the number of requests in flight. In JavaScript and Go, send the batches concurrently yourself: ```python Python theme={null} import random 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/indexes/target-an-index index = pc.index(host="INDEX_HOST") # Example data: 10,000 documents with a 128-dimension `embedding` field documents = [ {"_id": f"doc-{i}", "embedding": [random.random() for _ in range(128)]} for i in range(10000) ] # Send up to 10 requests of 200 documents at a time result = index.documents.batch_upsert( namespace="example-namespace", documents=documents, batch_size=200, max_concurrency=10, ) print(result) ``` ```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/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST', namespace: 'example-namespace' }); // Example data: 10,000 documents with a 128-dimension `embedding` field const documents = Array.from({ length: 10000 }, (_, i) => ({ _id: `doc-${i}`, embedding: Array.from({ length: 128 }, () => Math.random()), })); // Break the documents into batches of 200 const batches = []; for (let i = 0; i < documents.length; i += 200) { batches.push(documents.slice(i, i + 200)); } // Send all batches in parallel await Promise.all(batches.map((batch) => index.documents.upsert({ documents: batch }))); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "math/rand" "sync" "github.com/pinecone-io/go-pinecone/v7/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/indexes/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) } // Example data: 10,000 documents with a 128-dimension `embedding` field documents := make([]pinecone.Document, 10000) for i := range documents { embedding := make([]float32, 128) for j := range embedding { embedding[j] = rand.Float32() } documents[i] = pinecone.Document{"_id": fmt.Sprintf("doc-%d", i), "embedding": embedding} } // Send up to 10 requests of 200 documents at a time batchSize := 200 semaphore := make(chan struct{}, 10) errs := make(chan error, len(documents)/batchSize+1) var wg sync.WaitGroup for start := 0; start < len(documents); start += batchSize { batch := documents[start:min(start+batchSize, len(documents))] wg.Add(1) semaphore <- struct{}{} go func(start int, batch []pinecone.Document) { defer wg.Done() defer func() { <-semaphore }() if _, err := idxConnection.UpsertDocuments(ctx, &pinecone.UpsertDocumentsRequest{Documents: batch}); err != nil { errs <- fmt.Errorf("batch starting at %d: %w", start, err) } }(start, batch) } wg.Wait() close(errs) for err := range errs { log.Printf("Failed to upsert %v", err) } } ``` ## Upsert limits | Metric | Limit | | :- | :- | | Max [batch size](/guides/legacy/vectors-api/upsert-vectors#upsert-in-batches) for records with vectors | 1,000 records, up to 2 MB total | | Max batch size for records with text | 96 records | | Max documents per upsert request | 1,000, or 96 when the schema declares `embed` or `sparse_embed` | | 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](/guides/search/full-text-search/text-processing#tokens-and-analyzers) | 1,024 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 limit for text is lower because Pinecone converts that text to vectors at upsert time with [integrated embedding](/guides/indexes/index-data-overview#integrated-embedding), and 96 is the max batch size of the [hosted embedding models](/guides/indexes/index-configuration#embedding-models) doing the conversion. The 40 KB filterable metadata limit doesn't apply to `full_text_search` text fields. # Pinecone architecture Source: https://docs.pinecone.io/guides/get-started/architecture Learn how Pinecone is built, from organizations, projects, indexes, and namespaces down to the APIs and infrastructure that store and serve your data. Pinecone's architecture has two layers: the resource hierarchy that organizes your data, and the serverless infrastructure that stores and serves it. ## Resource hierarchy Your data in Pinecone is organized as a hierarchy of resources. An [organization](/guides/get-started/key-terms#organization) contains [projects](/guides/get-started/key-terms#project), a project contains [indexes](/guides/get-started/key-terms#index), and an index is divided into [namespaces](/guides/get-started/key-terms#namespace) that hold your [documents](/guides/get-started/key-terms#document) or [records](/guides/get-started/key-terms#record). For a definition of each object, see [Key terms](/guides/get-started/key-terms). This diagram shows an organization with two projects. The first project holds two indexes, and the first index is divided into three namespaces: ```mermaid theme={null} flowchart TB subgraph org["Organization"] direction TB subgraph p1["Project 1"] direction TB subgraph i1["Index 1"] direction TB ns1["Namespace 1"] ns2["Namespace 2"] ns3["Namespace 3"] end i2["Index 2"] end p2["Project 2"] end class ns1,ns2,ns3,i2,p2 pc-mermaid-item class p1,i1 pc-mermaid-group class org pc-mermaid-frame ``` ## Serverless infrastructure Pinecone runs as a managed service on AWS, GCP, and Azure. 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 data is stored in distributed [object storage](#object-storage). This diagram shows how the API gateway routes your application's requests to the control plane or to the data plane in your index's cloud region: ![Serverless overview diagram. An application sends requests to the API gateway. The gateway sends project and index requests to the global control plane, and data requests to the data plane in a cloud region. The data plane reads from and writes to object storage in the same region.](https://mintcdn.com/pinecone/4ZMbNRugM8zK8siL/images/serverless-overview-light.svg?fit=max\&auto=format\&n=4ZMbNRugM8zK8siL\&q=85\&s=f19539d8df6149ae78ccf0f181f89406) ### API gateway Every request to Pinecone includes an [API key](/admin/projects/manage-api-keys) that's assigned to a specific [project](/admin/projects/projects-overview). The API gateway first checks that your API key has access to the project. Then it routes your request to the global control plane (for managing projects and indexes) or a regional data plane (for reading and writing data). ### Control plane The global control plane manages resources like projects and indexes and tracks them in a dedicated database. It also handles billing and user management, and it coordinates operations across regions. ### Data plane The data plane handles all requests to write and read data in [indexes](/guides/indexes/index-data-overview) within a specific [cloud region](/guides/indexes/index-configuration#cloud-regions). Each index is divided into one or more logical [namespaces](/guides/indexes/index-data-overview#namespaces), and every read and write targets one namespace. Pinecone separates writes and reads into different paths, and each path scales independently with demand, so queries never slow down writes, and writes never slow down queries. ### Data-plane APIs Each index is created for, and served by, one data-plane API. The [Documents API](/guides/get-started/documents-api) serves document indexes and is the API to build on. The legacy Vectors API and legacy Records API serve legacy vector indexes and legacy integrated indexes, and they keep working. | | Documents API | Legacy Vectors API | Legacy Records API | | :- | :- | :- | :- | | You write | JSON documents with your own fields | An ID, a vector, and metadata | An ID, a text field, and metadata | | Who embeds | You, or Pinecone per field in the schema | You, outside Pinecone | Pinecone, with one model per index | | Source text lives | In its own `string` field | In a separate store, or in metadata | In metadata | | Search by | Full-text, vector, or text that Pinecone embeds | Vector | Text that Pinecone embeds | | Configured by | Schema | Dimension and metric | Model and text field | | Unit of data | [Document](/guides/get-started/key-terms#document) | [Record](/guides/get-started/key-terms#record) | Record | | Index | Document index | Legacy vector index | Legacy integrated index | To move data from a legacy index to a document index, see [Move to the Documents API](/guides/indexes/move-to-the-documents-api). ### Object storage Pinecone stores each namespace's data in distributed object storage as immutable files called slabs. The [index builder](#index-builder) creates slabs and optimizes them for querying. ## Write path This diagram shows the log writer recording a write request in the request log and passing the data to the index builder, which moves it from the memtable into a namespace's slabs: ![Write path diagram. A client sends a write request to the log writer. The log writer appends it to the request log in object storage and passes the data to the memtable in the index builder, which moves it into a namespace's slabs. Each namespace holds progressively larger slabs at levels 0, 1, and 2.](https://mintcdn.com/pinecone/4ZMbNRugM8zK8siL/images/serverless-write-path-light.svg?fit=max\&auto=format\&n=4ZMbNRugM8zK8siL\&q=85\&s=3ba778de0824e18b17dcdbe548c207bb) ### Request log When you send a write request (to add, update, or delete data), the [data plane](#data-plane) first logs the request with a unique sequence number (LSN). The sequence number keeps operations in order and tracks the state of the index. Pinecone then returns `200 OK`. Your write is durable at this point, and Pinecone processes it in the background. ### Index builder The index builder writes your data and its sequence number to an in-memory structure called a memtable. For an update or delete, it also tracks how queries should handle the old version. Periodically, the index builder moves data from the memtable into slabs in [object storage](#object-storage). Small slabs use lightweight indexing that needs few resources. As slabs grow, the index builder merges them into larger slabs with indexing that performs better at scale. Each slab gets indexing suited to its size, and the cost of heavier indexing is spread over the life of the namespace. > [!NOTE] > > All reads check the memtable, so you can search data immediately after you write it, before it reaches object storage. For more details, see [Query executors](#query-executors). ## Read path This diagram shows the query router merging recent data from the memtable with ranked results from the query executors, which fetch slabs from object storage when they aren't cached: ![Read path diagram. A client sends a query to the query router, whose logical plan targets slabs 1 and 2. The router sends the query to a query executor and gets the freshest data from the memtable in the index builder. The executor has slab 1 in memory and fetches slab 2 from object storage, then returns ranked results. The router sends the merged results to the client.](https://mintcdn.com/pinecone/4ZMbNRugM8zK8siL/images/serverless-read-path-light.svg?fit=max\&auto=format\&n=4ZMbNRugM8zK8siL\&q=85\&s=5a844a101ea9cbcdd29ada0c898addbe) ### Query routers When you send a search query, the [data plane](#data-plane) first checks your request against system limits, such as [rate and object limits](/reference/api/database-limits). The query router then finds the slabs that hold relevant data and sends your query to their executors. It also searches the memtable for recent data that isn't in object storage yet. ### Query executors Each query executor searches its assigned slabs and returns the most relevant candidates to the query router. If your query has a metadata filter, the executors exclude anything that doesn't match before finding the best matches. Slabs are usually cached in memory or on local SSD, which keeps queries fast. If a slab isn't cached, because it's being read for the first time or hasn't been used recently, the executor fetches it from object storage and caches it. The query router then merges the executors' results with the memtable results, removes duplicates, and returns the best matches. # Pinecone Documents API Source: https://docs.pinecone.io/guides/get-started/documents-api The Pinecone Documents API stores text, vectors, and metadata in one schema-defined index and serves full-text, semantic, and sparse-vector search from it. The Documents API is how you read and write data in Pinecone Database. It's built for agents and search apps that need to find an exact identifier as reliably as a concept. An embedding model can't reliably tell one SKU, error code, or order number from a similar one, so a vector search on its own can return the wrong result without raising an error. One document index serves both keyword (full-text) search and semantic search, so you don't need a separate keyword engine to keep in sync with your vectors. You don't have to generate embeddings yourself. When a text field declares `embed`, Pinecone embeds the text when you upsert it and embeds your query when you search. You can also bring your own dense or sparse vectors. ## Index schema Each document is a JSON object with fields you name, such as `title` or `category`. The index schema, set when you create the index, declares which fields are searchable and how: | Field | Declared as | Searched with | | - | - | - | | Text, such as a title or body | `string` with `full_text_search` | Full-text search, with BM25 ranking, Lucene query syntax (boolean operators, phrases, boosting, and fuzzy matching), and exact-term filters | | Text you want Pinecone to embed | `string` with `embed` or `sparse_embed` | Semantic or sparse-vector search on vectors Pinecone generates | | Vectors you bring | `dense_vector` or `sparse_vector` | Semantic or sparse-vector search | | Anything else, such as a category or year | Not declared | Metadata filters | A schema can declare several text fields, such as a title and a body, each with its own [text processing](/guides/search/full-text-search/text-processing) settings for language, stemming, stop words, or n-grams. One `string` field can also declare both `full_text_search` and `embed`, so the same text is searchable by keyword and by meaning. To design the fields for your own data, see [Data modeling](/guides/indexes/data-modeling). ## Search a document index Each search request ranks results by the clauses in `score_by`, and an optional `filter` narrows the candidates first. You can run these types of search: * [Full-text search](/guides/search/full-text-search) ranks by keyword relevance (BM25) with a `text` or `query_string` clause. * [Semantic search with integrated embedding](/guides/search/integrated-embedding) ranks by meaning with an `embed` clause, and Pinecone embeds your query. * [Semantic search with your own vectors](/guides/search/semantic-search) ranks by meaning with a `dense_vector` clause. * [Sparse-vector search](/guides/search/sparse-vector-search) ranks by term weights with a `sparse_embed` or `sparse_vector` clause. * [Semantic search filtered by text](/guides/search/filter-by-metadata#text-match-filters) ranks by meaning but keeps only documents whose full-text fields contain exact terms or phrases, using `$match_all`, `$match_any`, or `$match_phrase` in the `filter`. * [Hybrid search](/guides/search/hybrid-search) runs a full-text search and a semantic search and merges the results with [reciprocal rank fusion](/guides/search/reciprocal-rank-fusion). Full-text clauses can be combined in one request, but a vector or embedding clause must be the only one. Any search can also [filter on metadata](/guides/search/filter-by-metadata), such as `{"category": {"$eq": "accessories"}}`. For when to use each approach, see [Search overview](/guides/search/search-overview). ### Example In this example, the first search is a full-text search for an exact model number. The second is a semantic search with integrated embedding, filtered to accessories whose title contains that number: ```python Python expandable theme={null} import os import time from pinecone import Pinecone, SchemaBuilder pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) schema = ( SchemaBuilder() .add_string_field(name="title", full_text_search={"language": "en"}) .add_string_field(name="description", full_text_search={"language": "en"}, embed={"model": "llama-text-embed-v2"}) .build() ) pc.indexes.create(name="product-catalog", schema=schema) index = pc.index(name="product-catalog") index.documents.upsert( namespace="catalog", documents=[ {"_id": "1", "title": "KB-1024 wireless mechanical keyboard", "description": "Compact keyboard with brown switches and USB-C charging.", "category": "keyboards"}, {"_id": "2", "title": "KB-1024 replacement keycaps", "description": "Soft-touch keycaps that fit the KB-1024 and quiet each keystroke.", "category": "accessories"}, {"_id": "3", "title": "MS-300 silent mouse", "description": "A quiet mouse with soft clicks for shared offices.", "category": "accessories"}, ], ) time.sleep(10) # documents are indexed asynchronously # Full-text search: rank by exact terms (BM25) results = index.documents.search( namespace="catalog", top_k=3, score_by=[{"type": "text", "fields": ["title"], "query": "KB-1024"}], include_fields=["title"], ) for match in results.matches: print(match._id, match.title) # Semantic search filtered by text: rank by meaning, keep only documents that contain an exact term, and filter on metadata results = index.documents.search( namespace="catalog", top_k=3, score_by=[{"type": "embed", "fields": ["description"], "query": "make my typing quieter"}], filter={"$and": [{"title": {"$match_all": "KB-1024"}}, {"category": {"$eq": "accessories"}}]}, include_fields=["title"], ) for match in results.matches: print(match._id, match.title) ``` The first search returns both KB-1024 products. The second returns only the keycaps. The keyboard isn't an accessory, and the mouse's title doesn't contain KB-1024. ## Legacy indexes Indexes created before the Documents API keep working on the API they were created with: | Index | Created with | API | Learn more | | - | - | - | - | | Legacy vector index | `create_index` with `dimension` and `metric` | Legacy Vectors API | [Create a legacy vector index](/guides/legacy/vectors-api/create-a-vector-index) | | Legacy integrated index | `create_index_for_model` | Legacy Records API | [Create a legacy integrated index](/guides/legacy/records-api/create-an-integrated-index) | To move a legacy index to the Documents API, including converting it without reloading your data, see [Move to the Documents API](/guides/indexes/move-to-the-documents-api). # Pinecone key terms Source: https://docs.pinecone.io/guides/get-started/key-terms The key terms and objects in Pinecone and how they relate to each other. This page defines the key terms and objects in Pinecone. For how these objects nest together, see [Architecture](/guides/get-started/architecture#resource-hierarchy). ## Account and billing ### Organization An organization is a group of one or more [projects](#project) that use the same billing. Organizations allow one or more [users](/admin/organizations/manage-organization-members) to control billing and permissions for all of the projects belonging to the organization. For more information, see [Organizations overview](/admin/organizations/organizations-overview). ### 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](/admin/projects/manage-project-members) who belong to the project can access the indexes in that project. [API keys](#api-key) and [assistants](/guides/assistant/overview) are project-specific. For more information, see [Projects overview](/admin/projects/projects-overview). ### 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. ### 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/cost/understand-cost#query), [fetch](/guides/cost/understand-cost#fetch), and [list](/guides/cost/understand-cost#list). For how read units are calculated, see [Understand Pinecone cost](/guides/cost/understand-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/cost/understand-cost#upsert), [update](/guides/cost/understand-cost#update), and [delete](/guides/cost/understand-cost#delete). For how write units are calculated, see [Understand Pinecone cost](/guides/cost/understand-cost#write-units). ## Index Pinecone [serverless indexes](/guides/indexes/index-data-overview) hold your data as [documents](#document) or [records](#record), depending on how the index was created. One index per use case is the typical pattern. ### Document index A document index is an index created with a document schema. It holds [documents](#document) and is served by the [Documents API](/guides/get-started/documents-api). Because a document can combine vectors, text, and metadata, a single document index often covers what previously required two indexes. Pick the ranking signal per query with `score_by`. ### Legacy vector index A legacy vector index is an index created with a dense or sparse vector type. It holds [records](#record) and is served by the legacy Vectors API. New projects should use a [document index](#document-index). * In an index with dense vectors, each record has one [dense vector](#dense-vector). Records can also carry a [sparse vector](#sparse-vector) for single-index [hybrid search](/guides/legacy/vectors-api/hybrid-search-single-index). * In an index with sparse vectors, each record has one sparse vector. ### Namespace A namespace is a partition within an index. It divides [documents](#document) or [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/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/indexes/index-data-overview#namespaces). ### Backup A backup is a static copy of an index, including its schema. Backups only consume storage and can't be queried. You can create a backup from an index, and you can create a new index from that backup. The new index inherits the source index's schema, so it has the same fields, dimensions, and similarity metric, but it can have a different name. For more information, see [Understanding backups](/guides/indexes/backups-overview). ## Data ### Document A document is a JSON object with a required `_id` field, the ranking fields declared in the index's schema, and any number of metadata fields. It's the unit of data in a [document index](#document-index). A document can combine these ranking fields: * `string` fields with `full_text_search` enabled, for [full-text search](#full-text-search). * A `dense_vector` field, or a `string` field with `embed`, for [semantic search](#semantic-search). * A `sparse_vector` field, or a `string` field with `sparse_embed`, for [sparse-vector search](#sparse-vector-search). With `embed` and `sparse_embed`, Pinecone generates the vectors from your text using [integrated embedding](/guides/search/integrated-embedding). You choose the [scoring method](#scoring-methods) per query with `score_by`. Legacy vector indexes and legacy integrated indexes hold [records](#record) instead. For more information, see [Full-text search](/guides/search/full-text-search). #### Document fields * **Schema limits**: Up to 100 `string` fields with `full_text_search` enabled, at most one dense field (a `dense_vector` field or a `string` field with `embed`), and at most one sparse field (a `sparse_vector` field or a `string` field with `sparse_embed`) per index. * **Value shapes**: 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 metadata `string_list` field holds an array of strings. * **Metadata fields**: Any field on an upserted document that's 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**: Names must be unique, non-empty strings of 64 bytes or less. They can't start with `_` (reserved for system-managed fields like `_id` and `_score`) or `$` (reserved for filter operators). ### Record A record is the unit of data in a [legacy vector index](#legacy-vector-index). It contains: * A [record ID](#record-id). * One vector, or a dense and a sparse vector for single-index [hybrid search](/guides/search/hybrid-search). * Optional [metadata](#metadata). In a [legacy integrated index](/guides/legacy/records-api/create-an-integrated-index) created with `create_index_for_model`, 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, such as a text field ranked by BM25 and a `dense_vector` field for similarity, model it as a [document](#document). For more information, see [Upsert data](/guides/data/upsert-data). #### Record ID A record ID is a record's unique ID. [Use ID prefixes](/guides/indexes/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, and each number is a coordinate in that space. Vectors that are closer together in that space are semantically similar. Dense vectors power [semantic search](#semantic-search). 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/indexes/index-configuration#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 power [sparse-vector search](#sparse-vector-search), and they can coexist with dense vectors in a single legacy vector index for [hybrid search](/guides/legacy/vectors-api/hybrid-search-single-index) on the legacy Vectors API. 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/indexes/index-configuration#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 document or record to provide more context and enable additional [filtering capabilities](/guides/indexes/index-data-overview#metadata). For example, the original text that was embedded can be stored in the metadata. ## Search ### Full-text search Full-text search ranks documents by BM25 token matching, with optional Lucene query syntax, over `string` fields declared with `full_text_search`. These are often called text fields. Full-text search doesn't need a model. * **At index time**: Pinecone tokenizes text and records term frequencies and field lengths. * **At query time**: Pinecone computes BM25 scores, including inverse document frequency (IDF). * **Tokens**: A token is a unit produced by Pinecone's text analyzer (split on whitespace and punctuation, lowercased by default, and optionally stemmed), not the subword unit an embedding model uses internally. See [Tokens and analyzers](/guides/search/full-text-search/text-processing#tokens-and-analyzers) for the full pipeline. 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 more information, see [Full-text search](/guides/search/full-text-search). ### Semantic search When you search with a [dense vector](#dense-vector), Pinecone retrieves the documents or records whose dense vectors are most semantically similar to the query. This is also called nearest neighbor search, similarity search, or vector search. ### Sparse-vector search When you search with a [sparse vector](#sparse-vector), Pinecone retrieves the documents or records whose sparse vectors share the most weighted tokens with the query vector. This is also called sparse-vector retrieval. 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 search and [full-text search](#full-text-search) both retrieve on token-level signals, but they weight tokens differently: * **Full-text search**: Uses BM25, a statistical function with no model. Use it when you want a strong baseline with nothing to manage. * **Sparse-vector search**: Uses a learned encoder that weights tokens at index time and can expand to related terms. Use it when a learned encoder better captures your domain's term importance and synonyms. ### Scoring methods On a document index, you choose a scoring method per query with `score_by`. The value of `type` selects the method: * `text`: BM25 token matching over one or more text fields. * `query_string`: [Lucene query syntax](/guides/search/full-text-search/query-syntax) across one or more text fields, including cross-field boolean queries. * `dense_vector`: Vector similarity. * `sparse_vector`: Sparse-vector similarity. * `embed`: Vector similarity, with Pinecone embedding the query text using the field's `embed` model. * `sparse_embed`: Sparse-vector similarity, with Pinecone embedding the query text using the field's `sparse_embed` model. You can combine several `text` and `query_string` clauses in one query. Any other type must be the only clause. To combine two or more signals, restrict a dense search with a text-match [filter](#metadata-filters), or run separate searches and merge the results client-side. ### Metadata filters You can combine any scoring method with a metadata filter. Filters support: * **Logical operators**: `$and`, `$or`, and `$not`. * **Existence checks**: `$exists`. * **Text-match operators**: `$match_phrase`, `$match_all`, and `$match_any` match phrases and tokens in text fields. For more information, see [Metadata filter expressions](/guides/indexes/index-data-overview#metadata-filter-expressions). ### Standalone embedding and reranking Standalone embedding and reranking let you call [embedding models](/guides/indexes/index-configuration#embedding-models) and [reranking models](/guides/search/rerank-results#reranking-models) hosted on Pinecone's infrastructure directly, separately from index operations. # Pinecone Database Source: https://docs.pinecone.io/guides/get-started/overview Pinecone Database is a search engine for AI agents and applications. It serves full-text, semantic, and sparse-vector search and retrieval from one index. Pinecone Database powers retrieval for AI agents and applications, including search, recommendations, and long-term memory. You build on one API, the [Documents API](/guides/get-started/documents-api). You write JSON documents with your own field names, and the index schema declares how each searchable field is indexed, whether for full-text search, for embedding by Pinecone, or as a dense or sparse vector you bring. Any other field is stored as metadata you can filter on, so one index can serve whichever retrieval approach a query calls for. ## Get started > [card] [Quickstart](/guides/get-started/quickstart) > > Pick a search path and run your first search in minutes > [card] [AI coding tools](/integrations/ai-coding-tools) > > Use Pinecone with Claude Code, Codex, Cursor, and other agentic tools > [card] [MCP server](/guides/agents/mcp-server) > > Connect any MCP-compatible agent to Pinecone for search and index management ## What you can do With Pinecone Database, you can: * Find exact IDs, codes, and phrases with [full-text search](/guides/search/full-text-search), which ranks with BM25, accepts Lucene query syntax, and lets you set stemming, stop words, and n-grams per field. * Serve full-text search, [semantic search](/guides/search/semantic-search), [sparse-vector search](/guides/search/sparse-vector-search), and [hybrid search](/guides/search/hybrid-search) from one index. To choose an approach, see [Search overview](/guides/search/search-overview). * Upsert and query with text instead of vectors. With [integrated embedding](/guides/indexes/index-data-overview#integrated-embedding), Pinecone generates the vectors from your text server-side. * Narrow results with [metadata filters](/guides/search/filter-by-metadata), then [rerank](/guides/search/rerank-results) them for relevance. * Keep each tenant's data separate within one index by using [namespaces](/guides/data/implement-multitenancy). * Scale reads for sustained, high query volumes with [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview). * On the Standard and Enterprise plans, [convert a legacy index](/guides/indexes/convert-an-index) to a document index without reloading your data. For the code changes, see [Move to the Documents API](/guides/indexes/move-to-the-documents-api). * Run in production by [backing up](/guides/indexes/backups-overview) your indexes and deploying in your own cloud account with [Bring Your Own Cloud (BYOC)](/guides/production/bring-your-own-cloud). ## Learn > [card] [Documents API](/guides/get-started/documents-api) > > One schema for your text, vectors, and metadata, searched through one API > [card] [Key terms](/guides/get-started/key-terms) > > Organizations, projects, indexes, namespaces, documents, and records > [card] [Data modeling](/guides/indexes/data-modeling) > > Design the fields your index needs for the searches you'll run > [card] [Search overview](/guides/search/search-overview) > > Compare search types and choose the right approach for each query ## Resources > [card] [API reference](/reference) > > Details about the Pinecone APIs, SDKs, and architecture > [card] [Examples](/examples) > > Notebooks and sample apps with common AI patterns > [card] [Models](/models/overview) > > Embedding and reranking models hosted by Pinecone > [card] [Integrations](/integrations/overview) > > Third-party integrations for LangChain, LlamaIndex, and more > [card] [Troubleshooting](/admin/support/contact-support) > > Common errors, account help, and how to contact support > [card] [Changelog](/release-notes) > > What's new in Pinecone ## Other Pinecone products > [card] [Pinecone Assistant](/guides/assistant/overview) > > A managed service for RAG chat and agent applications grounded in your data > [card] [Pinecone Nexus](/guides/nexus/overview) > > The knowledge engine for agents, serving grounded, cited answers in one call # Pinecone quickstart Source: https://docs.pinecone.io/guides/get-started/quickstart Get started with Pinecone in minutes. Create an index that searches your text by meaning and by exact terms, load sample documents, and run both searches. One document index handles both kinds of search: by meaning, and by exact terms like IDs, error codes, and phrases. You upsert plain text, and Pinecone embeds it for you with [integrated embedding](/guides/search/integrated-embedding). ## Prerequisites * A Pinecone account and API key ([get one](https://app.pinecone.io) or [view pricing](https://www.pinecone.io/pricing/)). ## Let your agent set it up The quickest way to start is to let your AI coding agent do the setup: it designs your schema, ingests your data, and runs your first query, all conversationally. The steps below cover Claude Code and Codex, which share the same Pinecone skills. Using Cursor or another agent? See [all supported AI coding tools](/integrations/ai-coding-tools) for the equivalent setup. ### 1. Set your API key and install the plugin The plugin needs [Node.js](https://nodejs.org/) and [uv](https://docs.astral.sh/uv/getting-started/installation/) installed. The quickstart skill uses uv to run its bundled Python scripts. > [tab] Claude Code > > ```bash Terminal theme={null} > export PINECONE_API_KEY="YOUR_API_KEY" > claude plugin install pinecone > ``` > > > [!NOTE] > > > > Installing the plugin requires access to the [official Anthropic marketplace](https://code.claude.com/docs/en/discover-plugins#official-anthropic-marketplace). Claude Code adds this access automatically the first time you start it. If the install fails with a `Marketplace "claude-plugins-official" not found` error, your network or your organization's Claude Code setup is probably blocking it. > > Restart Claude Code to activate the plugin. > [tab] Codex > > ```bash Terminal theme={null} > export PINECONE_API_KEY="YOUR_API_KEY" > codex plugin marketplace add pinecone-io/pinecone-codex-plugin > codex plugin add pinecone --marketplace pinecone-codex-plugins > ``` > > Start Codex from the same shell so it picks up the key. To install from the ChatGPT desktop app instead, see the [Codex plugin](/integrations/codex#installation) page. ### 2. Run the quickstart command > [tab] Claude Code > > ```text Claude Code theme={null} > /pinecone:quickstart > ``` > [tab] Codex > > ```text Codex theme={null} > $pinecone:quickstart > ``` ## Set it up yourself Build the index with an SDK or the REST API. Its `chunk_text` field is set up the same way as the default `chunk_text` field in the [Pinecone console's create index form](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless). The steps run on sample documents, so you can finish first and then [use your own files](#use-your-own-files). > [!NOTE] > > If you already generate your own embeddings, store them in a `dense_vector` field instead of declaring `embed`. For the steps, see [Bring your own vectors](/guides/search/bring-your-own-vectors). ### 1. Install an SDK Install the Pinecone SDK for your language. Integrated embedding needs Python SDK `10.1.0` or later (Python 3.10+), Node.js SDK `9.1.0` or later (Node.js 22+), or Go SDK `7.1.0` or later (Go 1.25+, or Go 1.26+ for SDK `7.2.0` and later). The curl examples need no SDK, but they use `jq` to read the index host. ```bash Python theme={null} pip install --upgrade "pinecone>=10.1.0" ``` ```bash JavaScript theme={null} npm install "@pinecone-database/pinecone@>=9.1.0" ``` ```bash Go theme={null} go get github.com/pinecone-io/go-pinecone/v7/pinecone@latest ``` The JavaScript examples use top-level `await`, so run them as an ES module, such as a `.mjs` file. The Go examples build one `main` function: the first block is the full program, and each later block adds to it. ### 2. Set your API key Set your API key as an environment variable. The SDKs read it automatically, and the curl examples pass it in a header. ```bash Terminal theme={null} export PINECONE_API_KEY="YOUR_API_KEY" ``` ### 3. Create an index Declare one `string` field with both `full_text_search` and `embed`. Pinecone indexes the field's text for keyword (BM25) search and embeds it for semantic search, so one field supports both. An empty `embed` config uses the default model, `llama-text-embed-v2`, at 1,024 dimensions. Only searchable fields go in the schema; other fields are stored on the documents as metadata (capped at 40 KB per document). ```python Python theme={null} import os, time from pinecone import Pinecone, SchemaBuilder pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) schema = ( SchemaBuilder() .add_string_field("chunk_text", full_text_search={"language": "en"}, embed={}) .build() ) if not pc.indexes.exists(name="quickstart"): pc.indexes.create(name="quickstart", schema=schema) while not pc.indexes.describe(name="quickstart").status.ready: time.sleep(2) index = pc.index(name="quickstart") ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone(); // reads PINECONE_API_KEY await pc.indexes.create({ name: 'quickstart', schema: { fields: { chunk_text: { type: 'string', fullTextSearch: { language: 'en' }, embed: {} }, }, }, waitUntilReady: true, suppressConflicts: true, }); const index = pc.index({ name: 'quickstart', namespace: '__default__' }); ``` ```go Go theme={null} package main import ( "context" "log" "time" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{}) // reads PINECONE_API_KEY if err != nil { log.Fatal(err) } if _, err := pc.DescribeIndex(ctx, "quickstart"); err != nil { language := "en" _, err = pc.CreateIndex(ctx, &pinecone.CreateIndexRequest{ Name: "quickstart", Schema: pinecone.IndexSchema{ Fields: map[string]pinecone.IndexSchemaField{ "chunk_text": {String: &pinecone.StringField{ FullTextSearch: &pinecone.FullTextSearchConfig{Language: &language}, Embed: &pinecone.EmbedConfig{}, }}, }, }, }) if err != nil { log.Fatal(err) } } idx, err := pc.DescribeIndex(ctx, "quickstart") for err == nil && !idx.Status.Ready { time.Sleep(2 * time.Second) idx, err = pc.DescribeIndex(ctx, "quickstart") } if err != nil { log.Fatal(err) } index, err := pc.Index(pinecone.NewIndexConnParams{Host: idx.Host, Namespace: "__default__"}) if err != nil { log.Fatal(err) } } ``` ```bash curl theme={null} curl -X POST "https://api.pinecone.io/indexes" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "name": "quickstart", "schema": { "fields": { "chunk_text": { "type": "string", "full_text_search": { "language": "en" }, "embed": {} } } } }' # Wait until the index is ready, then save its host (requires jq) until curl -s "https://api.pinecone.io/indexes/quickstart" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" | jq -e '.status.ready' > /dev/null; do sleep 2 done INDEX_HOST=$(curl -s "https://api.pinecone.io/indexes/quickstart" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" | jq -r '.host') ``` ### 4. Load sample documents Each document has a required `_id`, plain text on the `chunk_text` field, and any metadata you want to filter on, like `category` here. Pinecone embeds the text on write, so you don't send vectors. Documents are indexed asynchronously, so the code waits 10 seconds before you search. If a search returns no results, wait a few seconds and run it again. ```python Python theme={null} index.documents.upsert( namespace="__default__", documents=[ {"_id": "1", "chunk_text": "Refund requests must be submitted within 30 days of purchase.", "category": "policy"}, {"_id": "2", "chunk_text": "Enterprise customers get support with a 4-hour response time.", "category": "policy"}, {"_id": "3", "chunk_text": "Error E1042: the connection timed out after 30 seconds. Retry with a longer timeout.", "category": "log"}, {"_id": "4", "chunk_text": "To reset your password, open Settings and choose Security.", "category": "support"}, {"_id": "5", "chunk_text": "Order 88231 shipped on 2026-08-20 via express courier.", "category": "order"}, ], ) time.sleep(10) # documents are indexed asynchronously, so wait a moment ``` ```javascript JavaScript theme={null} await index.documents.upsert({ documents: [ { _id: '1', chunk_text: 'Refund requests must be submitted within 30 days of purchase.', category: 'policy' }, { _id: '2', chunk_text: 'Enterprise customers get support with a 4-hour response time.', category: 'policy' }, { _id: '3', chunk_text: 'Error E1042: the connection timed out after 30 seconds. Retry with a longer timeout.', category: 'log' }, { _id: '4', chunk_text: 'To reset your password, open Settings and choose Security.', category: 'support' }, { _id: '5', chunk_text: 'Order 88231 shipped on 2026-08-20 via express courier.', category: 'order' }, ], }); await new Promise((resolve) => setTimeout(resolve, 10000)); // documents are indexed asynchronously, so wait a moment ``` ```go Go theme={null} // Add to the main function: _, err = index.UpsertDocuments(ctx, &pinecone.UpsertDocumentsRequest{ Documents: []pinecone.Document{ {"_id": "1", "chunk_text": "Refund requests must be submitted within 30 days of purchase.", "category": "policy"}, {"_id": "2", "chunk_text": "Enterprise customers get support with a 4-hour response time.", "category": "policy"}, {"_id": "3", "chunk_text": "Error E1042: the connection timed out after 30 seconds. Retry with a longer timeout.", "category": "log"}, {"_id": "4", "chunk_text": "To reset your password, open Settings and choose Security.", "category": "support"}, {"_id": "5", "chunk_text": "Order 88231 shipped on 2026-08-20 via express courier.", "category": "order"}, }, }) if err != nil { log.Fatal(err) } time.Sleep(10 * time.Second) // documents are indexed asynchronously, so wait a moment ``` ```bash curl theme={null} curl -X POST "https://$INDEX_HOST/namespaces/__default__/documents/upsert" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "documents": [ { "_id": "1", "chunk_text": "Refund requests must be submitted within 30 days of purchase.", "category": "policy" }, { "_id": "2", "chunk_text": "Enterprise customers get support with a 4-hour response time.", "category": "policy" }, { "_id": "3", "chunk_text": "Error E1042: the connection timed out after 30 seconds. Retry with a longer timeout.", "category": "log" }, { "_id": "4", "chunk_text": "To reset your password, open Settings and choose Security.", "category": "support" }, { "_id": "5", "chunk_text": "Order 88231 shipped on 2026-08-20 via express courier.", "category": "order" } ] }' sleep 10 # documents are indexed asynchronously, so wait a moment ``` ### 5. Search by meaning Score by `embed` and pass the query as text. Pinecone embeds the query with the same model it used for the documents and ranks them by semantic similarity, so a question finds the right passage even when it shares no words with it. The `filter` limits the search to documents whose `category` metadata is `policy`. ```python Python theme={null} meaning = index.documents.search( namespace="__default__", top_k=3, score_by=[{"type": "embed", "fields": ["chunk_text"], "query": "how do I get my money back?"}], filter={"category": {"$eq": "policy"}}, include_fields=["chunk_text"], ) for m in meaning.matches: print(m.id, f"{m.score:.3f}", m.chunk_text) ``` ```javascript JavaScript theme={null} const meaning = await index.documents.search({ topK: 3, scoreBy: [{ type: 'embed', fields: ['chunk_text'], query: 'how do I get my money back?' }], filter: { category: { $eq: 'policy' } }, includeFields: ['chunk_text'], }); for (const m of meaning.matches) { console.log(m._id, m._score.toFixed(3), m.chunk_text); } ``` ```go Go theme={null} // Add "fmt" to your imports, then add to the main function: meaningQuery := "how do I get my money back?" meaning, err := index.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{ TopK: 3, ScoreBy: []pinecone.DocumentScoringMethod{ {Type: pinecone.DocumentScoringTypeEmbed, Fields: []string{"chunk_text"}, Query: &meaningQuery}, }, Filter: map[string]interface{}{"category": map[string]interface{}{"$eq": "policy"}}, IncludeFields: []string{"chunk_text"}, }) if err != nil { log.Fatal(err) } for _, m := range meaning.Matches { fmt.Printf("%s %.3f %s\n", m.Id, *m.Score, m.Fields["chunk_text"]) } ``` ```bash curl theme={null} curl -X POST "https://$INDEX_HOST/namespaces/__default__/documents/search" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "top_k": 3, "score_by": [ { "type": "embed", "fields": ["chunk_text"], "query": "how do I get my money back?" } ], "filter": { "category": { "$eq": "policy" } }, "include_fields": ["chunk_text"] }' ``` Only the two policy documents are searched, and the refund policy ranks first: ```text Output theme={null} 1 0.417 Refund requests must be submitted within 30 days of purchase. 2 0.089 Enterprise customers get support with a 4-hour response time. ``` ### 6. Search by exact terms Score by `text` to rank the same field by BM25 keyword relevance, so an exact identifier like `E1042` surfaces the document that contains it. ```python Python theme={null} terms = index.documents.search( namespace="__default__", top_k=3, score_by=[{"type": "text", "fields": ["chunk_text"], "query": "E1042"}], include_fields=["chunk_text"], ) for m in terms.matches: print(m.id, f"{m.score:.3f}", m.chunk_text) ``` ```javascript JavaScript theme={null} const terms = await index.documents.search({ topK: 3, scoreBy: [{ type: 'text', fields: ['chunk_text'], query: 'E1042' }], includeFields: ['chunk_text'], }); for (const m of terms.matches) { console.log(m._id, m._score.toFixed(3), m.chunk_text); } ``` ```go Go theme={null} // Add to the main function: termsQuery := "E1042" terms, err := index.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{ TopK: 3, ScoreBy: []pinecone.DocumentScoringMethod{ {Type: pinecone.DocumentScoringTypeText, Fields: []string{"chunk_text"}, Query: &termsQuery}, }, IncludeFields: []string{"chunk_text"}, }) if err != nil { log.Fatal(err) } for _, m := range terms.Matches { fmt.Printf("%s %.3f %s\n", m.Id, *m.Score, m.Fields["chunk_text"]) } ``` ```bash curl theme={null} curl -X POST "https://$INDEX_HOST/namespaces/__default__/documents/search" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "top_k": 3, "score_by": [ { "type": "text", "fields": ["chunk_text"], "query": "E1042" } ], "include_fields": ["chunk_text"] }' ``` Only the document that contains the term matches: ```text Output theme={null} 3 1.225 Error E1042: the connection timed out after 30 seconds. Retry with a longer timeout. ``` Either search accepts a `filter`. For phrase matching and boolean queries, see the [query syntax reference](/guides/search/full-text-search/query-syntax). Each search returns its own ranking, and the scores are on different scales, so don't compare them across searches. To merge the two rankings into one list, use [reciprocal rank fusion](/guides/search/reciprocal-rank-fusion) in your client. ## Use your own files To search your own documents, upsert text from your files the same way. Pinecone doesn't extract or chunk files, so do those steps in your code before you upsert. If you already have embeddings for your files, see [Bring your own vectors](/guides/search/bring-your-own-vectors) instead. ### 1. Extract text from your files Convert each file (PDF, DOCX, HTML, and so on) to plain text using a parser of your choice. The result should be a list of records, each with an ID and text, like the `docs` list below. > [!NOTE] > > If you're searching images instead of text, embed them with a multimodal embedding model and store the vectors in a `dense_vector` field, as in [Bring your own vectors](/guides/search/bring-your-own-vectors). ```python Python theme={null} docs = [ {"id": "handbook-1", "text": "Refund requests must be submitted within 30 days of purchase."}, {"id": "handbook-2", "text": "Enterprise customers get support with a 4-hour response time."}, # ...extracted from your files ] ``` ```javascript JavaScript theme={null} const docs = [ { id: 'handbook-1', text: 'Refund requests must be submitted within 30 days of purchase.' }, { id: 'handbook-2', text: 'Enterprise customers get support with a 4-hour response time.' }, // ...extracted from your files ]; ``` ```go Go theme={null} // Add to the main function: type Doc struct{ ID, Text string } docs := []Doc{ {"handbook-1", "Refund requests must be submitted within 30 days of purchase."}, {"handbook-2", "Enterprise customers get support with a 4-hour response time."}, // ...extracted from your files } ``` ### 2. Chunk the text Split your text into smaller pieces so each one is a focused, searchable passage. The embedding model reads only the first 2,048 tokens of a value and truncates the rest, so keep chunks well under that. The function below is a simple length-based split. For smarter approaches (by sentence, token, or document structure), see [chunking strategies](https://www.pinecone.io/learn/chunking-strategies/). Each chunk ID starts with its source document's ID, so you can later [fetch, replace, or delete all of a document's chunks](/guides/data/manage-document-chunks) at once. ```python Python theme={null} def chunk(text, size=500): return [text[i:i + size] for i in range(0, len(text), size)] chunks = [ {"id": f"{d['id']}#{i}", "text": part} for d in docs for i, part in enumerate(chunk(d["text"])) ] ``` ```javascript JavaScript theme={null} const chunk = (text, size = 500) => { const parts = []; for (let i = 0; i < text.length; i += size) parts.push(text.slice(i, i + size)); return parts; }; const chunks = docs.flatMap((d) => chunk(d.text).map((part, i) => ({ id: `${d.id}#${i}`, text: part })), ); ``` ```go Go theme={null} // Add to the main function: chunk := func(text string, size int) []string { runes := []rune(text) var parts []string for i := 0; i < len(runes); i += size { parts = append(parts, string(runes[i:min(i+size, len(runes))])) } return parts } var chunks []Doc for _, d := range docs { for i, part := range chunk(d.Text, 500) { chunks = append(chunks, Doc{fmt.Sprintf("%s#%d", d.ID, i), part}) } } ``` ### 3. Upsert the chunks An index with an `embed` field accepts up to 96 documents per upsert, so send the chunks in batches. Then search them with the same calls as above. ```python Python theme={null} for i in range(0, len(chunks), 96): index.documents.upsert( namespace="__default__", documents=[ {"_id": c["id"], "chunk_text": c["text"]} for c in chunks[i:i + 96] ], ) ``` ```javascript JavaScript theme={null} for (let i = 0; i < chunks.length; i += 96) { await index.documents.upsert({ documents: chunks.slice(i, i + 96).map((c) => ({ _id: c.id, chunk_text: c.text })), }); } ``` ```go Go theme={null} // Add to the main function: for i := 0; i < len(chunks); i += 96 { var batch []pinecone.Document for _, c := range chunks[i:min(i+96, len(chunks))] { batch = append(batch, pinecone.Document{"_id": c.ID, "chunk_text": c.Text}) } if _, err := index.UpsertDocuments(ctx, &pinecone.UpsertDocumentsRequest{Documents: batch}); err != nil { log.Fatal(err) } } ``` For a large dataset in Python, use [`batch_upsert`](/guides/optimize/increase-throughput#upsert-in-batches), which sends batches in parallel and returns any failed batches so you can retry them. You can't [bulk import](/guides/data/import-data) into an index with an `embed` field. ## Next steps * [Design a schema](/guides/indexes/data-modeling) for your own data, with more than one searchable field. * [Choose an embedding model or dimension](/guides/search/integrated-embedding), or add `sparse_embed` for learned-sparse search. * [Filter by metadata](/guides/search/filter-by-metadata), including text-match filters on full-text search fields. # Back up an index Source: https://docs.pinecone.io/guides/indexes/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. ```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/v7/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: 2026-07" \ -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", "schema":{ "fields":{ "embedding":{ "type":"dense_vector", "description":null, "dimension":1024, "metric":"cosine" } } }, "record_count":96, "namespace_count":3, "size_bytes":1069169, "created_at":"2025-05-14T16:37:25.625540Z" } ``` > [!TIP] > > 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/v7/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: 2026-07" \ -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", "schema":{ "fields":{ "embedding":{ "type":"dense_vector", "description":null, "dimension":1024, "metric":"cosine" } } }, "record_count":98, "namespace_count":3, "size_bytes":1069169, "created_at":"2025-03-11T18:29:50.549505Z" } ``` > [!TIP] > > 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 doesn't 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/v7/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: 2026-07" \ -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", "schema":{ "fields":{ "embedding":{ "type":"dense_vector", "description":null, "dimension":1024, "metric":"cosine" } } }, "record_count":98, "namespace_count":3, "size_bytes":1069169, "created_at":"2025-03-11T18:29:50.549505Z" } ], "pagination":null } ``` > [!TIP] > > 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 doesn't 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/v7/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: 2026-07" \ -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", "schema": { "fields": { "sparse_embedding": { "type": "sparse_vector", "description": null } } }, "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", "schema": { "fields": { "embedding": { "type": "dense_vector", "description": null, "dimension": 1024, "metric": "cosine" } } }, "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", "schema": { "fields": { "embedding": { "type": "dense_vector", "description": null, "dimension": 1024, "metric": "cosine" } } }, "record_count": 98, "namespace_count": 3, "size_bytes": 1069169, "created_at": "2025-05-14T16:37:25.625540Z" } ], "pagination": null } ``` > [!TIP] > > 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/v7/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: 2026-07" ``` > [!TIP] > > 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 > [tab] Pinecone console > > 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. > [tab] API > > > [!NOTE] > > > > Scheduled backups require [API version](/reference/api/versioning) `2026-04` or later. > > To [create a backup schedule](/reference/api/latest/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: 2026-07" \ > -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 > [tab] Pinecone console > > 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. > [tab] API > > > [!NOTE] > > > > Scheduled backups require [API version](/reference/api/versioning) `2026-04` or later. > > You can [list schedules](/reference/api/latest/control-plane/list_backup_schedules), [update a schedule](/reference/api/latest/control-plane/update_backup_schedule) (e.g., to pause it or change the frequency), [delete a schedule](/reference/api/latest/control-plane/delete_backup_schedule), and [view the backup history](/reference/api/latest/control-plane/list_backup_schedule_history) for a schedule. Deleting a schedule doesn't delete any backups that were previously created by it. For more details, see [Scheduled backups](/guides/indexes/backups-overview#scheduled-backups). # Backups overview Source: https://docs.pinecone.io/guides/indexes/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/indexes/index-data-overview) that only consumes storage. It's a non-queryable representation of a set of records. You can [create a backup](/guides/indexes/back-up-an-index) of a serverless index, and you can [create a new serverless index from a backup](/guides/indexes/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/indexes/back-up-an-index#schedule-automated-backups). > [!NOTE] > > Scheduled backups require [API version](/reference/api/versioning) `2026-04` or later. 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: 2026-07" \ -H "Content-Type: application/json" \ -d '{ "name": "my-nightly-backup", "schedule": { "type": "time-based", "frequency": "daily" }, "retention": { "expire_after_days": 7 } }' ``` Deleting a schedule doesn't 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/latest/control-plane/create_backup_schedule) * [List backup schedules](/reference/api/latest/control-plane/list_backup_schedules) * [Describe backup schedule](/reference/api/latest/control-plane/describe_backup_schedule) * [Update backup schedule](/reference/api/latest/control-plane/update_backup_schedule) * [Delete backup schedule](/reference/api/latest/control-plane/delete_backup_schedule) * [List schedule history](/reference/api/latest/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 | > [!NOTE] > > Backups aren't available on the Starter or Builder plans. To create backups, [upgrade to the Standard or Enterprise plan](/admin/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 and incurs a cross-region transfer fee. For details, see [Restore to a different region](/guides/indexes/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 all serverless indexes, including document indexes with a schema (`full_text_search`, `dense_vector`, and `sparse_vector` fields) and indexes that use integrated embedding. * Backups aren't available for indexes in a project that uses [customer-managed encryption keys (CMEK)](/guides/production/configure-cmek). * A restored index inherits the source index's schema, including its `full_text_search`, `dense_vector`, `sparse_vector`, `embed`, and `sparse_embed` fields, and the restore request can't override it. ## Backup and restore cost * To understand how cost is calculated for backups and restores, see [Understand Pinecone cost](/guides/cost/understand-cost#backups-and-restores). * For up-to-date pricing information, see [Pricing](https://www.pinecone.io/pricing/). # Configure metadata indexing Source: https://docs.pinecone.io/guides/indexes/configure-metadata-indexing Limit metadata indexing in Pinecone to the fields you filter on, to keep index building and query execution fast. > [!NOTE] > > Setting metadata indexing requires the `2026-07` version of the API or later. Pinecone indexes all metadata fields by default. However, large amounts of metadata can cause slower [index building](/guides/get-started/architecture#index-builder) as well as slower [query execution](/guides/get-started/architecture#query-executors), particularly when data isn't 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 limit metadata indexing when you create an index with [integrated embedding](/guides/indexes/index-data-overview#integrated-embedding), or at [namespace creation](/reference/api/latest/data-plane/createnamespace) for any index: * Index-level metadata indexing rules apply to all namespaces that don't have their own rules. * Namespace-level metadata indexing rules override index-level rules. A document index doesn't accept metadata fields in its schema at creation, so limit its metadata indexing at the namespace level. For example, if you store records that represent chunks of a document, each with many metadata fields, but you plan to filter on only a few, index just those fields. Set `filterable` to `true` for each field to index. To leave a field unindexed, omit it (`filterable: false` isn't supported). > [!WARNING] > > 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/create-for-model" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "name": "example-index-metadata", "cloud": "aws", "region": "us-east-1", "embed": { "model": "llama-text-embed-v2", "field_map": { "text": "chunk_text" } }, "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/indexes/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-07" \ -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: 2026-07" ``` ```shell Describe namespace theme={null} # To learn how to get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/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: 2026-07" ``` The response includes the `schema` object with the names of the metadata fields explicitly indexed during index or namespace creation, alongside any search fields declared on the index. > [!NOTE] > > The response doesn't include unindexed metadata fields or metadata fields indexed by default. ```json Describe index theme={null} { "name": "example-index-metadata", "host": "example-index-metadata-fa77d8e.svc.aped-4627-b74a.pinecone.io", "status": { "ready": true, "state": "Ready" }, "deployment": { "deployment_type": "managed", "region": "us-east-1", "cloud": "aws", "environment": "aped-4627-b74a" }, "read_capacity": { "mode": "OnDemand", "status": { "state": "Ready", "current_shards": null, "current_replicas": null } }, "schema": { "fields": { "chunk_text": { "type": "semantic_text", "description": null, "model": "llama-text-embed-v2", "dimension": 1024, "metric": "cosine", "write_parameters": { "dimension": 1024, "input_type": "passage", "truncate": "END" }, "read_parameters": { "dimension": 1024, "input_type": "query", "truncate": "END" } }, "document_id": { "filterable": true }, "document_title": { "filterable": true }, "chunk_number": { "filterable": true }, "document_url": { "filterable": true }, "created_at": { "filterable": true } } }, "tags": null, "deletion_protection": "disabled" } ``` ```json Describe namespace theme={null} { "name": "example-namespace", "record_count": "20000", "size_bytes": "10000000", "schema": { "fields": { "document_title": { "filterable": true }, "document_url": { "filterable": true }, "chunk_number": { "filterable": true }, "document_id": { "filterable": true }, "created_at": { "filterable": true } } } } ``` # Convert an index to a document index Source: https://docs.pinecone.io/guides/indexes/convert-an-index Convert a Pinecone serverless legacy vector index or legacy integrated index into a new document index with full-text search, while the source keeps serving. Converting builds a new document index from the records in a serverless legacy vector index or legacy integrated index, so you can run full-text search on that data without re-ingesting it. > [!NOTE] > > This feature is available on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). ## What a conversion does * **Source**: The source index keeps serving reads and writes before, during, and after the conversion. * **Snapshot**: The job copies the source as it stood when the job starts, as a backup does. Writes to the source after you send the request might not be in the new index. * **IDs and fields**: Each record becomes a document with the same ID, and its fields are filled by name, as described in [Plan the schema](#plan-the-schema). * **Namespaces**: Each source namespace becomes a namespace of the same name in the new index. Namespaces that have never held records are skipped. * **Location**: The new index is created in the source's cloud and region, or in the source's environment for a Bring Your Own Cloud (BYOC) index. It's encrypted with the source's customer-managed encryption keys (CMEK) when the source has them. * **Billing**: A conversion is charged at the [import](/guides/cost/understand-cost#imports) rate, by the size of the source's data. A job that fails because of your data is charged for the data it read. A canceled job, or one that fails because of an internal error, isn't charged. Both indexes are billed for storage until you delete the source. For a BYOC index, neither the conversion nor storage has a separate charge, because [BYOC is billed](/guides/production/bring-your-own-cloud#pricing) by environment and node. ## Limitations * Only serverless and BYOC indexes in the `Ready` state can be converted, including indexes on [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview). An index in any other state, such as one that's being deleted, has failed, or is disabled, is rejected with a `412`. * Pod-based indexes can't be converted. [Migrate the index to serverless](/guides/legacy/pod-based-indexes/migrate-a-pod-based-index-to-serverless) first, then convert the serverless index it creates. * A few BYOC environments don't support conversion, and an index in one of them is rejected with a `400`. To ask about yours, [contact support](https://app.pinecone.io/organizations/-/settings/support/ticket). * An index that already has a document schema can't be converted, and neither can a text index. * With on-demand read capacity, the new index can take at most 1,000 GB of source data. For a larger source, set `read_capacity` to [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview) in the request, or contact support. * The new index can't use the source's name or any name already taken in the project, including by an index an earlier conversion created. A name that's taken is rejected with a `409`. You can convert the same source more than once, as long as each new index has its own name. ## Plan the schema The `schema` you pass in the request defines the new index, and Pinecone fills its fields from each source record as follows. For how to design the schema itself, see [Data modeling](/guides/indexes/data-modeling). | Source | Target field | | - | - | | Dense vector | The schema's one `dense_vector` field, or its `string` field with `embed`. | | Sparse vector | The schema's one `sparse_vector` field, or its `string` field with `sparse_embed`. | | Metadata key that matches a full-text field name | The `string` field with `full_text_search` of the same name. The value moves into that field and is no longer metadata. | | All other metadata | Carried over unchanged, and still filterable. | A schema field that no source record has a value for isn't an error. The field is empty in the new index, and searching it returns no results, so name each full-text field after a metadata key your records already use. ### Schema requirements * The dense field has to use the source's dimension and metric. A mismatch is rejected with a `400` that names the dimension or metric to set. * A schema made only of the reserved `_values` and `_sparse_values` fields is rejected, because it describes a legacy vector index rather than a document index. ### Sources with sparse vectors Records that carry sparse values need a field those values can go into, even when the source is an index of dense vectors. Without one, those records can't be converted, and [`error_mode`](#handle-mismatched-records) decides what happens to them. For a sparse index, the schema needs a `sparse_vector` field and no `dense_vector` field. In the new index, the dense and sparse vectors are separate fields, and a search ranks by one of them. To combine both, run a dense search and a sparse search and merge the results with [reciprocal rank fusion](/guides/search/reciprocal-rank-fusion). ### Legacy integrated indexes For an index created with `create_index_for_model`, declare a `string` field named after the source's embedded text field and give it `embed` (or `sparse_embed`) with the source's model. The vectors carry over, so your text isn't embedded again. Pinecone doesn't add this field for you. If you declare only a `dense_vector` field, the conversion succeeds, but the new index has no integrated embedding. A `string` field with `embed` is rejected with a `400` when the source isn't a legacy integrated index, or when the field's name or model doesn't match the source's. ### Handle mismatched records `error_mode.on_error` decides how the job treats a source record the schema can't hold, such as a record whose metadata value for a `full_text_search` field is a number instead of a string. * `abort` is the default. The conversion fails, and the job's `error` names the record and the reason. * `continue` skips the record and counts it in the job's `records_skipped`. ## Run a conversion This example converts `support-tickets`, a serverless index of 1024-dimension cosine vectors whose records carry `ticket_text`, `product`, and `priority` metadata. The new index, `support-tickets-docs`, keeps the vectors for semantic search and indexes `ticket_text` for full-text search, with `product` and `priority` still filterable. ### 1. Check the source index Read the source's dimension and metric, which your schema has to match, and confirm that its state is `Ready`. ```bash Request theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -X GET https://api.pinecone.io/indexes/support-tickets \ -H "Accept: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" ``` ```json Response expandable theme={null} { "name": "support-tickets", "host": "support-tickets-govk0nt.svc.aped-4627-b74a.pinecone.io", "status": { "ready": true, "state": "Ready" }, "deployment": { "deployment_type": "managed", "region": "us-east-1", "cloud": "aws", "environment": "aped-4627-b74a" }, "read_capacity": { "mode": "OnDemand", "status": { "state": "Ready", "current_shards": null, "current_replicas": null } }, "schema": { "fields": { "_values": { "type": "dense_vector", "description": null, "dimension": 1024, "metric": "cosine" }, "_sparse_values": { "type": "sparse_vector", "description": null } } }, "tags": null, "deletion_protection": "disabled" } ``` A legacy vector index always reports both reserved fields, `_values` for dense vectors and `_sparse_values` for sparse vectors, whether or not its records carry sparse values. ### 2. Start the conversion Use the [Convert an index into a document index](/reference/api/2026-07/control-plane/convert_index) operation, passing the name of the new index and the schema you want it to have. The `embedding` field takes the source's dense vectors, and the `ticket_text` field is filled from the `ticket_text` metadata key on each record. `on_error` is set to `continue` so that a record with a malformed `ticket_text` value is skipped instead of failing the whole job. ```bash Request expandable theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl https://api.pinecone.io/indexes/support-tickets/convert \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "name": "support-tickets-docs", "schema": { "fields": { "embedding": { "type": "dense_vector", "dimension": 1024, "metric": "cosine" }, "ticket_text": { "type": "string", "full_text_search": { "language": "en" } } } }, "error_mode": { "on_error": "continue" } }' ``` ```json Response theme={null} { "conversion_job_id": "670e8400-e29b-41d4-a716-446655440001", "index_id": "123e4567-e89b-12d3-a456-426614174000" } ``` The request returns as soon as the new index is created in the `Initializing` state and the job is queued. You can also set `tags`, `deletion_protection`, and `read_capacity` on the new index in the same request. If you leave them out, the new index copies the source's tags, while deletion protection is disabled and read capacity is on-demand, whatever the source uses. ### 3. Track the conversion job Pass the `conversion_job_id` from the previous step to the [Describe a conversion job](/reference/api/2026-07/control-plane/describe_conversion_job) operation to get the job's status and progress. ```bash Request theme={null} PINECONE_API_KEY="YOUR_API_KEY" JOB_ID="670e8400-e29b-41d4-a716-446655440001" curl -X GET "https://api.pinecone.io/conversion-jobs/$JOB_ID" \ -H "Accept: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" ``` ```json Response expandable theme={null} { "conversion_job_id": "670e8400-e29b-41d4-a716-446655440001", "source_index_name": "support-tickets", "source_index_id": "670e8400-e29b-41d4-a716-446655440000", "target_index_name": "support-tickets-docs", "target_index_id": "123e4567-e89b-12d3-a456-426614174000", "status": "InProgress", "error_mode": { "on_error": "continue" }, "percent_complete": 42.5, "records_converted": 425000, "records_skipped": 3, "error": null, "created_at": "2026-10-07T10:30:00Z", "completed_at": null } ``` A job is `Pending` until it starts, `InProgress` while it runs, and then `Completed`, `Failed`, or `Cancelled`. `percent_complete` is absent until the job starts, `completed_at` is `null` until it ends, and `error` is `null` unless the job fails. ### 4. Confirm the new index is ready When the job reaches `Completed`, the new index moves from `Initializing` to `Ready`. ```bash Request theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -X GET https://api.pinecone.io/indexes/support-tickets-docs \ -H "Accept: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" ``` ```json Response expandable theme={null} { "name": "support-tickets-docs", "host": "support-tickets-docs-govk0nt.svc.aped-4627-b74a.pinecone.io", "status": { "ready": true, "state": "Ready" }, "deployment": { "deployment_type": "managed", "region": "us-east-1", "cloud": "aws", "environment": "aped-4627-b74a" }, "read_capacity": { "mode": "OnDemand", "status": { "state": "Ready", "current_shards": null, "current_replicas": null } }, "schema": { "fields": { "embedding": { "type": "dense_vector", "description": null, "dimension": 1024, "metric": "cosine" }, "ticket_text": { "type": "string", "description": null, "full_text_search": { "language": "en", "stemming": false, "stop_words": false }, "store_text": true } } }, "tags": null, "deletion_protection": "disabled" } ``` Each document carries the ID its record had, the vector in `embedding`, the ticket text in `ticket_text`, and `product` and `priority` as filterable metadata. Read and write the index through the Documents API, where you can rank by BM25 on `ticket_text` with [full-text search](/guides/search/full-text-search) or by vector similarity on `embedding`, and filter on `product` and `priority` as before. ## Switch to the new index The new index has its own name and host, and you read and write it through the [Documents API](/guides/get-started/documents-api), so your application's write and search calls change. Until the new index is `Ready`, it rejects reads and writes with a `401` and the message `Not ready`. ### 1. Replay writes made during the conversion The new index holds the source as it stood when the job started, so upserts and deletes sent to the source after your request might not be in it. Either pause writes to the source until you switch, or log them and replay them to the new index once it's `Ready`. A replayed upsert is a document. The record's ID goes in `_id`, its vector goes in the dense field, and its metadata keys become top-level fields. An upsert replaces the whole document, so send every field, not only the ones that changed. ```bash Upsert theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="support-tickets-docs-govk0nt.svc.aped-4627-b74a.pinecone.io" VECTOR="[0.12, 0.45, 0.33, 0.81]" # The record's 1024-dimension vector curl "https://$INDEX_HOST/namespaces/__default__/documents/upsert" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "documents": [ { "_id": "ticket-1742", "embedding": '"$VECTOR"', "ticket_text": "Refund not applied after plan downgrade", "product": "billing", "priority": "high" } ] }' ``` ```bash Delete theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="support-tickets-docs-govk0nt.svc.aped-4627-b74a.pinecone.io" curl "https://$INDEX_HOST/namespaces/__default__/documents/delete" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "ids": ["ticket-1733"] }' ``` ### 2. Point your searches at the new index Send searches to the new index's host, which the describe response in [Confirm the new index is ready](#confirm-the-new-index-is-ready) returns. A legacy Vectors API query by vector becomes a `dense_vector` clause on `embedding` in `score_by`. The `filter` carries over unchanged, and `include_fields` names the fields to return. ```bash Request theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="support-tickets-docs-govk0nt.svc.aped-4627-b74a.pinecone.io" QUERY_VECTOR="[0.12, 0.45, 0.33, 0.81]" # A 1024-dimension query vector curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "score_by": [ { "type": "dense_vector", "fields": ["embedding"], "values": '"$QUERY_VECTOR"' } ], "filter": {"product": {"$eq": "billing"}}, "include_fields": ["ticket_text", "priority"], "top_k": 5 }' ``` ```json Response theme={null} { "matches": [ { "_id": "ticket-1742", "_score": 0.92, "ticket_text": "Refund not applied after plan downgrade", "priority": "high" } ], "namespace": "__default__", "usage": { "read_units": 1 } } ``` Matches come back with `_id` and `_score` in place of `id` and `score`. To rank by keywords in `ticket_text` instead, see [Full-text search](/guides/search/full-text-search). Confirm the new index returns the results you expect before you move on. ### 3. Delete the source index When you no longer need the source, [delete it](/guides/indexes/manage-indexes#delete-an-index). Don't delete it while a job is still reading it, because that fails the job. Deleting the source doesn't remove its completed conversion job. ## Manage conversion jobs ### List conversion jobs The [List conversion jobs](/reference/api/2026-07/control-plane/list_conversion_jobs) operation returns the project's conversion jobs, newest first. Use this to find the job behind an index you don't recognize, or the earlier job that claimed a name you want. ```bash Request theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -X GET "https://api.pinecone.io/conversion-jobs?limit=10" \ -H "Accept: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" ``` ```json Response expandable theme={null} { "data": [ { "conversion_job_id": "670e8400-e29b-41d4-a716-446655440001", "source_index_name": "support-tickets", "source_index_id": "670e8400-e29b-41d4-a716-446655440000", "target_index_name": "support-tickets-docs", "target_index_id": "123e4567-e89b-12d3-a456-426614174000", "status": "Completed", "error_mode": { "on_error": "continue" }, "percent_complete": 100, "records_converted": 1000000, "records_skipped": 3, "error": null, "created_at": "2026-10-07T10:30:00Z", "completed_at": "2026-10-07T11:05:00Z" } ], "pagination": { "next": "dXNlcl9pZD11c2VyXzE=" } } ``` To get the next page, pass the response's `pagination.next` token as the `paginationToken` query parameter. ### Cancel a conversion job The [Cancel a conversion job](/reference/api/2026-07/control-plane/cancel_conversion_job) operation stops a job that's `Pending` or `InProgress` and leaves the index it was filling in the `InitializationFailed` state. ```bash Request theme={null} PINECONE_API_KEY="YOUR_API_KEY" JOB_ID="670e8400-e29b-41d4-a716-446655440001" curl -X POST "https://api.pinecone.io/conversion-jobs/$JOB_ID/cancel" \ -H "Accept: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" ``` ```json Response expandable theme={null} { "conversion_job_id": "670e8400-e29b-41d4-a716-446655440001", "source_index_name": "support-tickets", "source_index_id": "670e8400-e29b-41d4-a716-446655440000", "target_index_name": "support-tickets-docs", "target_index_id": "123e4567-e89b-12d3-a456-426614174000", "status": "Cancelled", "error_mode": { "on_error": "continue" }, "percent_complete": 42.5, "records_converted": 425000, "records_skipped": 3, "error": null, "created_at": "2026-10-07T10:30:00Z", "completed_at": "2026-10-07T10:48:00Z" } ``` The response is the job as it stands after the request, so canceling a job that has already ended changes nothing and returns the job as it was. To reuse the index's name, see [Troubleshooting](#troubleshooting). ## Troubleshooting A job that fails or is canceled leaves its index in the `InitializationFailed` state. The index holds no usable data and keeps its name, so [delete it](/guides/indexes/manage-indexes#delete-an-index) before you convert into that name again. When a job fails because of your data, `error` says what went wrong. With the default `on_error` of `abort`, it names the record the new index couldn't take and the reason, as in this trimmed job. A job that fails because of an internal error leaves `error` as `null`. ```json theme={null} { "conversion_job_id": "670e8400-e29b-41d4-a716-446655440001", "status": "Failed", "error": "Record with id 'ticket-1742': metadata field `ticket_text` must be a string to fill the full-text field of that name" } ``` Fix the schema so it can hold that record, or set `on_error` to `continue` to skip records like it, then start a new conversion. With `continue`, a job that skips every record in a namespace still fails, because nothing was written to the new index. A job also fails when the source has no indexed records. New writes can take a few minutes to be indexed for conversion, even after queries return them, so if you wrote to the source just before converting, wait, delete the new index, and start the conversion again. These errors are returned when you start a conversion, before a job exists: | Status | Cause | Fix | | - | - | - | | `400` | The source is pod-based, in a BYOC environment that doesn't support conversion, a text index, or already has a document schema, or the new index has the source's name | The message names the problem | | `400` | The schema can't hold the source's vectors, or `on_error` isn't `abort` or `continue`. For example, a vector field is missing or doubled, a sparse index's schema has a dense field, a dimension, metric, or embedding doesn't match the source, or the schema has only `_values` and `_sparse_values` | The message names the problem and the value to use | | `403` | The organization is on the Starter or Builder plan, the API key can't create indexes, or the project's index quota is exhausted | Upgrade to Standard or Enterprise, use a key with `control::index::create`, or raise the quota | | `404` | The source index doesn't exist | Check the index name in the request path | | `409` | An index with that name already exists, possibly from an earlier conversion | Choose another name, or [list conversion jobs](#list-conversion-jobs) to find the earlier job | | `412` | The source index isn't `Ready`, for example because it's being deleted, has failed, or is disabled | Wait until it's `Ready`, then retry. The message says what state the source is in | # Create an index Source: https://docs.pinecone.io/guides/indexes/create-an-index Create a Pinecone serverless index for full-text (BM25), semantic (dense vector), sparse-vector, or hybrid search with a document schema. A Pinecone index lets you store and search your data. A document index stores JSON documents whose fields you declare in a schema at creation. It can combine dense vector, sparse vector, and full-text (`string`) fields in one document, so a single index serves [full-text search](/guides/search/full-text-search), [semantic search](/guides/search/semantic-search), and [sparse-vector search](/guides/search/sparse-vector-search). To create a legacy vector index, see [Create a vector index](/guides/legacy/vectors-api/create-a-vector-index). To create a legacy integrated index, see [Create an integrated index](/guides/legacy/records-api/create-an-integrated-index). > [!TIP] > > You can create an index using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless). ## Create a document index 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, and at query time you pick the ranking signal with `score_by`. Any other fields you upsert are stored as metadata, auto-indexed for filtering at upsert time. > [!NOTE] > > Full-text search and integrated embedding are different features. A `string` field with `full_text_search` is indexed for BM25 keyword ranking and Lucene queries. It doesn't create vectors or call an embedding model. To have Pinecone turn a field's text into vectors, use [integrated embedding](/guides/search/integrated-embedding): declare `embed` or `sparse_embed` on a `string` field in a document index. The legacy `create_index_for_model` path does this too, creating a [legacy integrated index](/guides/legacy/records-api/create-an-integrated-index) served by the legacy Records API. Indexes with document schemas use API version `2026-07`, supported through REST and the Python (v10 or later), Node.js (v9 or later), and Go (v7 or later) SDKs. 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. ```python Python theme={null} import os from pinecone import Pinecone, SchemaBuilder pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) schema = ( SchemaBuilder() .add_string_field(name="body", full_text_search={}) .build() ) pc.indexes.create(name="articles", schema=schema) ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -X POST "https://api.pinecone.io/indexes" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -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 `string` fields with `full_text_search` and `dense_vector` ranking fields together, and the same schema can also include a `sparse_vector` field. A single search request ranks by one scoring type. Multi-field BM25 is supported: use multiple `text` clauses on different fields, or one `query_string` clause spanning fields. Any scoring method can be combined with metadata filters, including text-match filters (`$match_phrase`, `$match_all`, `$match_any`) on `string` fields with `full_text_search`. ```python Python theme={null} import os from pinecone import Pinecone, SchemaBuilder pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) schema = ( SchemaBuilder() .add_string_field(name="title", full_text_search={}) .add_string_field(name="body", full_text_search={}) .add_dense_vector_field(name="embedding", dimension=1536, metric="cosine") .build() ) pc.indexes.create(name="articles-multi", schema=schema) ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -X POST "https://api.pinecone.io/indexes" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -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. `string_list`, `float`, and `boolean` fields are always metadata, and a `string` field is metadata unless it sets `full_text_search`, `embed`, or `sparse_embed`. Declaring a metadata-only field in the schema is rejected at index creation. To index only the metadata fields you filter on, see [Configure metadata indexing](/guides/indexes/configure-metadata-indexing). ### Integrated embedding On a document index, declare `embed` or `sparse_embed` on a `string` field. Pinecone then embeds its text on write and the query text at search time, so you upsert and search with plain text instead of vectors. See [Integrated embedding](/guides/search/integrated-embedding) for the schema, examples, and limits. 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). > [!NOTE] > > You can't add, remove, or modify a document index's fields after you create it. To change a schema, [delete the index](/guides/indexes/manage-indexes#delete-an-index) and create a new one. To move an existing legacy vector index or legacy integrated index onto a document schema, [convert it](/guides/indexes/convert-an-index) instead of reloading your data. ## Create an index from a backup You can create an index from a backup. For more details, see [Restore an index](/guides/indexes/restore-an-index). ## Wait for the index to be ready A new index of any type can't accept data until its `status.ready` field is `true`. The Python SDK waits for this by default, and the Node.js SDK waits when you pass `waitUntilReady: true`. If you call the API directly, [describe the index](/guides/indexes/manage-indexes#describe-an-index) repeatedly until `status.ready` is `true`, then upsert. # Data modeling Source: https://docs.pinecone.io/guides/indexes/data-modeling Model data in Pinecone as documents in a document index, choose a document schema, and plan IDs and metadata. Pinecone stores your data as [documents](#documents) in a document index. A document can hold full-text fields, vectors you generate yourself, text that Pinecone embeds, and metadata, so one shape covers single-signal and multi-signal workloads. Legacy vector indexes and legacy integrated indexes store [records](#records-in-legacy-indexes) instead. > [!TIP] > > Deciding how tenants share indexes and namespaces? See [Design for multitenancy](/guides/data/design-for-multitenancy). ## Documents A document is a JSON object in a document index, read and written through the [Documents API](/guides/get-started/documents-api). It has a required `_id`, values for the ranking fields declared in the index's schema, and any number of metadata fields. At query time, you choose which ranking field to search with `score_by`. You declare the schema when you create the index, and you can't change it afterward. The schema supports these ranking field types: * `string` with `full_text_search`: Indexed for [full-text search](/guides/search/full-text-search) with BM25 ranking and Lucene queries. `{}` uses the defaults, and the optional settings are `language`, `stemming`, `stop_words`, and `ngram`. Lowercasing and the token length cap are server-applied and can't be changed. * `string` with `embed` (dense) or `sparse_embed` (learned-sparse): Uses [integrated embedding](/guides/search/integrated-embedding). Pinecone embeds the text with a hosted model on write and embeds the query text at search time, so you upsert and search with plain text. The stored text is also full-text searchable by default. * `dense_vector`: An array of floats from your embedding model, indexed for approximate nearest neighbor (ANN) [semantic search](/guides/search/semantic-search). * `sparse_vector`: An object with parallel `indices` (token positions) and `values` (token weights) arrays, indexed for [sparse-vector search](/guides/search/sparse-vector-search). A schema can declare up to 100 full-text-searchable `string` fields, counting `embed` and `sparse_embed` fields that store their text, but at most one dense field (`dense_vector`, or a `string` field with `embed`) and one sparse field (`sparse_vector`, or a `string` field with `sparse_embed`). Fields you don't declare in the schema are metadata. Pinecone stores them on the document, returns them via `include_fields`, and indexes them for filtering. For supported types and limits, see [Include metadata](#include-metadata). For example, in an index whose schema declares `title` and `body` as full-text-search fields and `embedding` as a `dense_vector`, a document with a `category` metadata field looks like this: ```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 names must be unique, non-empty, and at most 64 bytes. They can't start with `_` (reserved for system fields like `_id` and `_score`) or `$` (reserved for filter operators). > [!NOTE] > > Pinecone scores and returns whole documents: `top_k` and `_score` apply per document, and Pinecone doesn't split a document into chunks. To retrieve parts of long content such as articles, PDFs, or transcripts, chunk it in your application before upsert and store each chunk as its own document, as shown in [Manage document chunks](/guides/data/manage-document-chunks). ### Choose a schema | To rank by | Declare | Guide | | - | - | - | | Keyword relevance (BM25) | One or more `string` fields with `full_text_search` | [Full-text search overview](/guides/search/full-text-search) | | Meaning, with Pinecone generating the vectors | A `string` field with `embed` or `sparse_embed` | [Integrated embedding](/guides/search/integrated-embedding) | | Your own dense or sparse vectors | A `dense_vector` or `sparse_vector` field | [Search with a dense vector](/guides/search/semantic-search#search-with-a-dense-vector), [Sparse-vector search](/guides/search/sparse-vector-search) | | Keyword and semantic signals together | A dense field and `string` fields with `full_text_search` | [Hybrid search overview](/guides/search/hybrid-search) | ### Schema validation Pinecone validates each document in an [upsert](/reference/api/latest/data-plane/upsert_documents) request against the schema. If any document fails, the whole request fails and nothing is written. | Scenario | Result | | - | - | | A value doesn't match its schema field's declared type | Error | | A document or request exceeds a size or count limit | Error | | A field name starts with `_` or `$` | Error | | A document is missing `_id` | Error | | A document is missing a `dense_vector` field, or a `string` field with `embed`, that the schema declares | Error | | A document has no schema fields, only `_id` and metadata | Error | | A document is missing any other schema field | OK | | A field isn't in the schema | Stored as metadata and indexed for filtering | ## Records in legacy indexes Records are the unit of data in a [legacy vector index](/guides/legacy/vectors-api/create-a-vector-index), read and written through the legacy Vectors API. You generate the vectors with an embedding model of your choice. Each record has these parts: * **ID**: A unique string identifier. * **Vector**: A dense vector for [semantic search](/guides/search/semantic-search), a sparse vector for [sparse-vector search](/guides/search/sparse-vector-search), or both for [hybrid search](/guides/search/hybrid-search) in a single index. * **Metadata** (optional): Flat key-value pairs (nested objects aren't supported) that you can filter on when searching or deleting. See [Include metadata](#include-metadata). ```json Dense theme={null} { "id": "document1#chunk1", "values": [0.0236663818359375, -0.032989501953125, ..., -0.01041412353515625, 0.0086669921875], "metadata": { "document_id": "document1", "chunk_number": 1, "chunk_text": "First chunk of the document content..." } } ``` ```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", "chunk_number": 1, "chunk_text": "First chunk of the document content..." } } ``` ```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", "chunk_number": 1, "chunk_text": "First chunk of the document content..." } } ``` To [import records from object storage](/guides/data/import-data#3-prepare-your-data), format them as Parquet. > [!NOTE] > > A legacy integrated index, created with `create_index_for_model` and served by the legacy Records API, also accepts records with raw text in place of a vector. For new projects, use a document index with [integrated embedding](/guides/search/integrated-embedding) instead, which can combine embedding and full-text search on the same field. ## Use structured IDs Give IDs a structured, human-readable format, with prefixes that reflect the data, for example: * **Document chunks**: `document_id#chunk_number` * **User data**: `user_id#data_type#item_id` * **Multitenant data**: `tenant_id#document_id#chunk_id` Use a delimiter that doesn't appear elsewhere in your IDs, such as `#`, `_`, or `:`. Prefixes let you [fetch every chunk of a source document](/guides/data/manage-document-chunks#fetch-all-chunks-of-a-document) by prefix, and they make IDs easier to read when you inspect your data. ## Include metadata Include [metadata](/guides/indexes/index-data-overview#metadata) fields that support your application's key operations, for example: * **Filter searches**: Add fields for time ranges, categories, or other criteria to [filter searches](/guides/search/filter-by-metadata). * **Link related chunks**: Use fields like `document_id` and `chunk_number` to group a document's chunks, so you can [delete](/guides/data/manage-document-chunks#delete-chunks) or [replace](/guides/data/manage-document-chunks#replace-a-chunked-document) them together. * **Link back to the source**: Include fields like `document_url` to display results or trace them back to the original content. Metadata values must be one of these types: * String * Number (stored as a 64-bit float) * Boolean * List of strings > [!NOTE] > > Each record or document can hold up to 40 KB of metadata. Schema fields on a document aren't metadata and don't count toward this limit. Each `string` schema field, including one with `embed` or `sparse_embed`, is limited to 100 KB, and stored text is limited to 10,000 tokens. # Index configuration Source: https://docs.pinecone.io/guides/indexes/index-configuration Reference for the naming rules, cloud regions, similarity metrics, and hosted embedding models you choose when you create a Pinecone index. When you create a Pinecone index, you choose a name, the cloud region where it's hosted, a similarity metric for dense vectors, and, for integrated embedding, a hosted embedding model. To index only the metadata fields you filter on, rather than all of them, see [Configure metadata indexing](/guides/indexes/configure-metadata-indexing). ## Index names An index name must be unique within its project and 1 to 45 characters long. It can contain only lowercase letters, numbers, and hyphens (`-`), and it must start and end with a letter or number. ## 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 can't be changed after a serverless index is created. > [!NOTE] > > 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](/admin/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/). > [!NOTE] > > Indexes that store [sparse vectors](/guides/get-started/key-terms#sparse-vector) must use the `dotproduct` metric. > [accordion] Euclidean > > 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's one of the most commonly used distance metrics. For an example, see the [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**. > [accordion] Cosine > > 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 the [generative question answering example](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/gen-qa-openai.ipynb). > [accordion] Dotproduct > > This multiplies two vectors to measure how similar they are. The more positive the result, the closer the two vectors are in direction. For an example, see the [semantic search example](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/semantic-search.ipynb). ## Embedding models Pinecone hosts these embedding models. You can use them for [integrated embedding](/guides/search/integrated-embedding), where Pinecone embeds text as you upsert and search, and some of them for [standalone embedding](/reference/api/latest/inference/generate-vectors). * Dense: * [`gemini-embedding-2`](/models/gemini-embedding-2) * [`llama-text-embed-v2`](/models/llama-text-embed-v2) * [`multilingual-e5-large`](/models/multilingual-e5-large) * [`text-embedding-3-large`](/models/text-embedding-3-large) * [`text-embedding-3-small`](/models/text-embedding-3-small) * Sparse: * [`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0) Each model's page lists the parameters it accepts and its specs, such as dimension, max tokens, metric, supported API, and plan. To compare the models, see the [model gallery](/models/overview). > [!NOTE] > > To understand how cost is calculated for embedding, see [Embedding cost](/guides/cost/understand-cost#embedding). To get model details via the API, see [List models](/reference/api/latest/inference/list-available-models) and [Describe a model](/reference/api/latest/inference/describe-a-model). # Index data overview Source: https://docs.pinecone.io/guides/indexes/index-data-overview Learn how indexing works in Pinecone: serverless indexes, schemas, namespaces, integrated embedding, and metadata filtering. ## Indexes In Pinecone, you store data in an index, typically one per use case. Every index is defined by a **schema** that declares its fields. What the schema can hold, and which API reads and writes the index, is set when you create it. New indexes are document indexes. Legacy vector indexes keep working for existing workloads. ### Document index You define a `schema` with `pc.indexes.create` (or `POST /indexes`). * One schema can combine `dense_vector`, `sparse_vector`, and `full_text_search`-enabled `string` fields. * A single index can serve [full-text search](/guides/search/full-text-search) (BM25 with Lucene queries), [semantic search](/guides/search/semantic-search), and [sparse-vector search](/guides/search/sparse-vector-search) together, often covering what previously required two indexes. * Holds [documents](/guides/get-started/key-terms#document), read and written through the [Documents API](/guides/get-started/documents-api). Pick the ranking signal per query with `score_by`. ### Legacy vector index Created with `pc.create_index(dimension=..., metric=..., vector_type=...)`. You don't declare fields yourself; the SDK builds the schema from the dimension, metric, and vector type you provide. * Holds [records](/guides/get-started/key-terms#record), read and written through the legacy Vectors API. * Serves [dense and sparse vector queries](/guides/legacy/vectors-api/query-vectors). For how to create one, see [Create a legacy vector index](/guides/legacy/vectors-api/create-a-vector-index). > [!NOTE] > > As of API version `2026-07`, `POST /indexes` in the REST API is schema-only. The SDKs still accept `dimension`, `metric`, and `vector_type` and create a legacy vector index. Existing indexes keep working unchanged on the API they were created with. See [Move to the Documents API](/guides/indexes/move-to-the-documents-api) for what changed and whether it affects your code. ## Search approaches How you rank results depends on the fields your index declares. ### Full-text search Full-text search is **BM25 token matching with Lucene query syntax** over text fields in your schema, `string` fields you've declared with `full_text_search` enabled. No model required: Pinecone handles tokenization, IDF, and length normalization at index time and BM25 scoring at query time. When you search, you rank results via `score_by`: `text` (BM25), `query_string` (Lucene), `dense_vector`, or `sparse_vector`. All scoring methods can be combined with metadata filters, including the text match operators (`$match_phrase`, `$match_all`, `$match_any`) for phrase and token matching. For example: ```json theme={null} { "score_by": [{ "type": "text", "fields": ["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, such as SKUs, error messages, code, and named entities. For semantic similarity over natural-language queries, see [Semantic search](#semantic-search). For retrieval with a learned sparse encoder, see [Sparse-vector search](#sparse-vector-search). Learn more: * [Full-text search guide](/guides/search/full-text-search) * [Schema definition](/guides/search/full-text-search#schema-definition) * [Upsert documents](/reference/api/latest/data-plane/upsert_documents) ### Semantic search 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/key-terms#dense-vector). Learn more: * [Create an index for dense vectors](/guides/legacy/vectors-api/create-a-vector-index#dense-vectors) * [Upsert dense vectors](/guides/data/upsert-data#upsert-dense-vectors) * [Semantic search](/guides/search/semantic-search) ### Sparse-vector search A sparse vector represents tokens (or token-like features) and their weights, with the vast majority of dimensions zero. A query returns records that share the most weighted tokens with the query vector, which is called **sparse-vector search**. Sparse vectors come from a sparse embedding model. Pinecone hosts [`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0); you can also bring your own. For the underlying concept and the distinction from full-text search, see [Sparse-vector search](/guides/get-started/key-terms#sparse-vector-search). Learn more: * [Create an index for sparse vectors](/guides/legacy/vectors-api/create-a-vector-index#sparse-vectors) * [Upsert sparse vectors](/guides/data/upsert-data#upsert-sparse-vectors) * [Sparse-vector search](/guides/search/sparse-vector-search) #### Limitations Indexes of sparse vectors have the following limitations: * Max non-zero values per sparse vector: 2048 * Max upserts per second per index of sparse vectors: 10 * Max queries per second per index of sparse vectors: 100 * Max `top_k` value per query: 10,000 > [!NOTE] > > You may get fewer than `top_k` results if `top_k` is larger than the number of sparse vectors in your index that match your query. That is, any vectors where the dotproduct score is `0` will be discarded. * Max query results size: 4 MB > [!TIP] > > Semantic search can miss exact keyword matches, while keyword search can miss semantically related results. To get the best of both, use [hybrid search](/guides/search/hybrid-search) — combine a keyword signal (BM25 or sparse) with a dense signal at query time, often with reranking. ## Namespaces Within an index, records or documents are partitioned into namespaces, and all [upserts](/guides/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/data/implement-multitenancy) for end-to-end guidance. * **Faster queries:** When you divide your data into namespaces in a logical way, you speed up queries by ensuring only relevant records or documents are scanned. The same applies to fetching them, listing their IDs, and other data operations. Namespaces are created automatically during [upsert](/guides/data/upsert-data), or you can create one ahead of time. To create, list, describe, or delete namespaces, see [Manage namespaces](/guides/data/manage-namespaces). To give a namespace a stable name you can repoint without a code change, see [Namespace aliases](/guides/data/namespace-aliases/overview). In this document index, an upsert writes to one namespace and a query reads from another: ```mermaid theme={null} flowchart LR upsert["Upsert"] --> ns1 query["Query"] --> ns2 subgraph index["Document index"] direction TB subgraph ns3["Namespace 3"] direction LR c1["Document 1"] ~~~ cn["Document n"] end subgraph ns2["Namespace 2"] direction LR b1["Document 1"] ~~~ bn["Document n"] end subgraph ns1["Namespace 1"] direction LR a1["Document 1"] ~~~ an["Document n"] end end class upsert,query pc-mermaid-action class a1,an,b1,bn,c1,cn pc-mermaid-item class ns1,ns2,ns3 pc-mermaid-group class index pc-mermaid-frame ``` > [!NOTE] > > [Namespaces per serverless index](/reference/api/database-limits/object-limits) vary by plan (100 on Starter to 1,000,000 on Enterprise). Pinecone can accommodate more for specific use cases. If your application needs a higher limit, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ## Vector embedding A schema declares the vector fields your index uses: a [dense vector](/guides/get-started/key-terms#dense-vector) field, a [sparse vector](/guides/get-started/key-terms#sparse-vector) field, or both. Dense vectors represent the semantics of data such as text, images, and audio; sparse vectors capture keyword information. To turn your source data into vectors, you use an embedding model. You can either use Pinecone's integrated embedding models to convert your data to vectors automatically, or use an external embedding model and bring your own vectors to Pinecone. ### Integrated embedding On a document index, declare `embed` (or `sparse_embed`) on a `string` field, and Pinecone generates the vectors from the field's text when you upsert and when you search. You send and query with plain text, and Pinecone uses the same [hosted model](/models/overview) both times. For a step-by-step walkthrough, see the [quickstart](/guides/get-started/quickstart#set-it-up-yourself). For model options, dimensions, and limits, see [Integrated embedding](/guides/search/integrated-embedding). Legacy integrated indexes created with `create_index_for_model` work differently. See [Create a legacy integrated index](/guides/legacy/records-api/create-an-integrated-index). ### Bring your own vectors If you generate embeddings yourself, store them in a `dense_vector` field whose dimension and metric match your model. Pinecone doesn't embed anything for you: you embed each document before you upsert it and each query before you search, with the same model. This fits a model Pinecone doesn't host, a model you've fine-tuned, or vectors you've already computed. For the steps, see [Bring your own vectors](/guides/search/bring-your-own-vectors). ## Metadata Every record has an ID and a vector, and every document has an `_id` and the fields its schema declares. Either can also carry metadata: extra key-value fields you filter on at query time. In a legacy vector index, you pass metadata as an explicit object with each vector. With integrated embedding or in a document index, extra fields you upsert are stored as metadata automatically. Pinecone indexes metadata for filtering, so a query can include a [metadata filter](/guides/search/filter-by-metadata) to limit the search. Searches without a metadata filter don't consider metadata and search the entire namespace. All metadata fields are indexed by default; to index only the fields you filter on, see [Configure metadata indexing](/guides/indexes/configure-metadata-indexing). ### Metadata format * Metadata fields must be key-value pairs in a flat JSON object. Nested JSON objects aren't 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 40 KB of metadata per record or document. `full_text_search` string fields aren't metadata and don't count toward this limit. Each `full_text_search` string field is limited to 100 KB and 10,000 tokens. ### Metadata filter expressions Pinecone's filtering language supports the following operators: | Operator | Function | Supported types | | :- | :- | :- | | `$eq` | Matches records or documents with metadata values that are equal to a specified value. Example: `{"genre": {"$eq": "documentary"}}` | Number, string, boolean | | `$ne` | Matches records or documents with metadata values that aren't equal to a specified value. Example: `{"genre": {"$ne": "drama"}}` | Number, string, boolean | | `$gt` | Matches records or documents with metadata values that are greater than a specified value. Example: `{"year": {"$gt": 2019}}` | Number | | `$gte` | Matches records or documents with metadata values that are greater than or equal to a specified value. Example:`{"year": {"$gte": 2020}}` | Number | | `$lt` | Matches records or documents with metadata values that are less than a specified value. Example: `{"year": {"$lt": 2020}}` | Number | | `$lte` | Matches records or documents with metadata values that are less than or equal to a specified value. Example: `{"year": {"$lte": 2020}}` | Number | | `$in` | Matches records or documents with metadata values that are in a specified array. The array can hold up to [10,000 values](/reference/api/database-limits/operation-limits#metadata-filter-limits). Example: `{"genre": {"$in": ["comedy", "documentary"]}}` | String, number | | `$nin` | Matches records or documents with metadata values that aren't in a specified array. The array can hold up to [10,000 values](/reference/api/database-limits/operation-limits#metadata-filter-limits). Example: `{"genre": {"$nin": ["comedy", "documentary"]}}` | String, number | | `$exists` | Matches records or documents 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}}]}` | - | | `$not` | Matches records or documents that don't match the wrapped clause. Example: `{"genre": {"$not": {"$eq": "drama"}}}` | - | At the top level, list one or more fields (combined with implicit AND) or combine clauses with the logical operators `$and` and `$or`. Use `$not` to negate a clause, as shown in the table. A bare comparison operator (like `$gt`) can't appear at the top level. Nest it under a field. A metadata field can hold an array of strings, such as `{"genre": ["comedy", "documentary"]}`. A filter on that field matches when any value in the array satisfies it, so each of these filters matches: ```json JSON theme={null} {"genre": "comedy"} {"genre": {"$in": ["documentary", "action"]}} {"$and": [{"genre": "comedy"}, {"genre": "documentary"}]} ``` These filters don't match, because the array has no `"drama"` value and because `$ne` and `$nin` exclude an item when any of its values matches: ```json JSON theme={null} {"$and": [{"genre": "comedy"}, {"genre": "drama"}]} {"genre": {"$ne": "comedy"}} ``` A filter value can't be an array. To match several values, use `$in`. These filters are invalid and return a `400` error: ```json JSON theme={null} {"genre": ["comedy", "documentary"]} {"genre": {"$eq": ["comedy", "documentary"]}} ``` # Manage serverless indexes Source: https://docs.pinecone.io/guides/indexes/manage-indexes List, describe, configure, and delete serverless indexes in Pinecone, including tags and deletion protection. This page shows you how to manage your existing serverless indexes. > [!NOTE] > > On API version `2026-07`, the REST `describe_index` and `list_indexes` responses replace the top-level `dimension`, `metric`, `vector_type`, and `spec` with top-level `deployment`, `read_capacity`, and `schema` objects, so `dimension` and `metric` now appear on the schema's dense-vector field. The `curl` examples below show this shape. The SDKs return both the new fields and the older top-level ones for backward compatibility, so the SDK examples still show `dimension`, `metric`, and `spec`. See [Move to the Documents API](/guides/indexes/move-to-the-documents-api) for details. ## 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/v7/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: 2026-07" ``` 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", "host": "docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io", "status": { "ready": true, "state": "Ready" }, "deployment": { "deployment_type": "managed", "region": "us-east-1", "cloud": "aws", "environment": "aped-4627-b74a" }, "read_capacity": { "mode": "OnDemand", "status": { "state": "Ready", "current_shards": null, "current_replicas": null } }, "schema": { "fields": { "sparse_embedding": { "type": "sparse_vector", "description": null } } }, "tags": { "environment": "development" }, "deletion_protection": "disabled" }, { "name": "docs-example-dense", "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io", "status": { "ready": true, "state": "Ready" }, "deployment": { "deployment_type": "managed", "region": "us-east-1", "cloud": "aws", "environment": "aped-4627-b74a" }, "read_capacity": { "mode": "OnDemand", "status": { "state": "Ready", "current_shards": null, "current_replicas": null } }, "schema": { "fields": { "chunk_text": { "type": "string", "description": null, "full_text_search": { "language": "en", "stemming": false, "stop_words": false } }, "embedding": { "type": "dense_vector", "description": null, "dimension": 1536, "metric": "cosine" } } }, "tags": { "environment": "development" }, "deletion_protection": "disabled" } ] } ``` 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 an 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/v7/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: 2026-07" ``` 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", "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io", "status": { "ready": true, "state": "Ready" }, "deployment": { "deployment_type": "managed", "region": "us-east-1", "cloud": "aws", "environment": "aped-4627-b74a" }, "read_capacity": { "mode": "OnDemand", "status": { "state": "Ready", "current_shards": null, "current_replicas": null } }, "schema": { "fields": { "chunk_text": { "type": "string", "description": null, "full_text_search": { "language": "en", "stemming": false, "stop_words": false } }, "embedding": { "type": "dense_vector", "description": null, "dimension": 1536, "metric": "cosine" } } }, "tags": { "environment": "development" }, "deletion_protection": "disabled" } ``` > [!WARNING] > > **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 an 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 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/v7/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: 2026-07" ``` 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/indexes/manage-indexes#configure-deletion-protection). > [!TIP] > > 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 On a legacy integrated index, [integrated embedding](/guides/legacy/records-api/create-an-integrated-index) lets you upsert and search without extra steps for embedding data. To configure an existing serverless index for an embedding model, use the [Configure an index](/reference/api/latest/control-plane/configure_index) operation as follows: * Set `embed.model` to one of [Pinecone's hosted embedding models](/guides/indexes/index-configuration#embedding-models). * Set `embed.field_map` to the name of the field in your source document that contains the data for embedding. > [!WARNING] > > 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 > [!NOTE] > > 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/indexes/create-an-index) or after its been created. In both cases, you set the `deletion_protection` parameter to `enabled`. > [!WARNING] > > Enabling deletion protection does *not* prevent [namespace deletions](/guides/data/manage-namespaces#delete-a-namespace). To enable deletion protection when creating a new index: > [!NOTE] > > Document-schema creation is currently available through the Python, JavaScript, and Go SDKs and REST. The Java tab creates a legacy vector index. See [Create an index](/guides/indexes/create-an-index). ```python Python theme={null} # pip install pinecone # Serverless index with a document schema from pinecone import Pinecone, SchemaBuilder pc = Pinecone(api_key="YOUR_API_KEY") schema = ( SchemaBuilder() .add_dense_vector_field(name="embedding", dimension=1536, metric="cosine") .build() ) pc.indexes.create( name="docs-example", deployment={"deployment_type": "managed", "cloud": "aws", "region": "us-east-1"}, schema=schema, deletion_protection="enabled" ) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone // Serverless index with a document schema import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.indexes.create({ name: 'docs-example', deployment: { deploymentType: 'managed', cloud: 'aws', region: 'us-east-1', }, schema: { fields: { embedding: { type: 'dense_vector', dimension: 1536, metric: 'cosine', }, }, }, deletionProtection: 'enabled', }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; // 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", "enabled", null); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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 with a document schema deletionProtection := pinecone.DeletionProtectionEnabled idx, err := pc.CreateIndex(ctx, &pinecone.CreateIndexRequest{ Name: "docs-example", Deployment: &pinecone.IndexDeployment{ Managed: &pinecone.ManagedDeployment{ Cloud: pinecone.CloudAWS, Region: "us-east-1", }, }, Schema: pinecone.IndexSchema{ Fields: map[string]pinecone.IndexSchemaField{ "embedding": { DenseVector: &pinecone.DenseVectorField{ Dimension: 1536, Metric: pinecone.IndexMetricCosine, }, }, }, }, DeletionProtection: &deletionProtection, }) if err != nil { log.Fatalf("Failed to create index: %v", err) } fmt.Printf("Successfully created 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: 2026-07" \ -d '{ "name": "docs-example", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "embedding": { "type": "dense_vector", "dimension": 1536, "metric": "cosine" } } }, "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; public class ConfigureIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.configureServerlessIndex("docs-example", "enabled", null, null); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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: 2026-07" \ -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; public class ConfigureIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.configureServerlessIndex("docs-example", "disabled", null, null); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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: 2026-07" \ -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/indexes/create-an-index) or configuring an existing index. To add tags when creating a new index: > [!NOTE] > > Document-schema creation is currently available through the Python, JavaScript, and Go SDKs and REST. The Java tab creates a legacy vector index. See [Create an index](/guides/indexes/create-an-index). ```python Python theme={null} from pinecone import Pinecone, SchemaBuilder pc = Pinecone(api_key="YOUR_API_KEY") schema = ( SchemaBuilder() .add_dense_vector_field(name="embedding", dimension=1536, metric="cosine") .build() ) pc.indexes.create( name="docs-example", deployment={"deployment_type": "managed", "cloud": "aws", "region": "us-east-1"}, schema=schema, deletion_protection="disabled", tags={ "example": "tag", "environment": "development" } ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.indexes.create({ name: 'docs-example', deployment: { deploymentType: 'managed', cloud: 'aws', region: 'us-east-1', }, schema: { fields: { embedding: { type: 'dense_vector', dimension: 1536, metric: 'cosine', }, }, }, deletionProtection: 'disabled', tags: { example: 'tag', environment: 'development', }, }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; 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", "disabled", tags); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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 with a document schema deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreateIndex(ctx, &pinecone.CreateIndexRequest{ Name: "docs-example", Deployment: &pinecone.IndexDeployment{ Managed: &pinecone.ManagedDeployment{ Cloud: pinecone.CloudAWS, Region: "us-east-1", }, }, Schema: pinecone.IndexSchema{ Fields: map[string]pinecone.IndexSchemaField{ "embedding": { DenseVector: &pinecone.DenseVectorField{ Dimension: 1536, Metric: pinecone.IndexMetricCosine, }, }, }, }, DeletionProtection: &deletionProtection, Tags: &pinecone.IndexTags{ "example": "tag", "environment": "development", }, }) if err != nil { log.Fatalf("Failed to create index: %v", err) } fmt.Printf("Successfully created 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: 2026-07" \ -d '{ "name": "docs-example", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "embedding": { "type": "dense_vector", "dimension": 1536, "metric": "cosine" } } }, "tags": { "example": "tag", "environment": "development" }, "deletion_protection": "disabled" }' ``` > [!TIP] > > 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 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", "enabled", tags, null); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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: 2026-07" \ -d '{ "tags": { "example": "tag", "environment": "development" } }' ``` > [!TIP] > > 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/indexes/manage-indexes) in a project or [get information about a specific index](/guides/indexes/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 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", "enabled", tags, null); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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: 2026-07" \ -d '{ "tags": { "example": "" } }' ``` > [!TIP] > > 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/indexes/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/v7/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: 2026-07" \ -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", "schema":{ "fields":{ "embedding":{ "type":"dense_vector", "description":null, "dimension":1024, "metric":"cosine" } } }, "record_count":98, "namespace_count":3, "size_bytes":1069169, "created_at":"2025-03-11T18:29:50.549505Z" } ], "pagination":null } ``` > [!TIP] > > 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. # Move to the Documents API Source: https://docs.pinecone.io/guides/indexes/move-to-the-documents-api Move your data from a legacy vector index or legacy integrated index to a document index, and update your code to call the Documents API. An index stays on the API it was created with. An index on the legacy Vectors API or legacy Records API never moves to the [Documents API](/guides/get-started/documents-api) on its own, even after you upgrade your SDK, and requests sent to the wrong API are refused. To use the Documents API, put your data in a new document index and point your code at it. Your legacy indexes and the code that calls them keep working in the meantime. ## Move your data To move a serverless or Bring Your Own Cloud (BYOC) index without reloading your data, [convert it](/guides/indexes/convert-an-index). Pinecone creates a new document index with the schema you choose and fills it from the source index's records, and the source index is left unchanged. Conversion is available on Standard and Enterprise plans. If you can't convert your index, or you want to reshape your data on the way in, create a new index and load your data into it: ### 1. Upgrade your SDK Upgrade to a `2026-07` SDK (Python v10 or later, Node.js v9 or later, or Go v7 or later), or use the REST API. The Java SDK doesn't support `2026-07` yet, so call the REST API from Java. ### 2. Create a document index [Create a new index](/guides/indexes/create-an-index) with the [schema](/guides/indexes/data-modeling) you want. Add a `deployment` only if you need a specific deployment type, cloud, or region; otherwise it defaults to managed serverless. ### 3. Load your data Load your data from its source with [upsert](/guides/data/upsert-data) or [import](/guides/data/import-data). Each record becomes a document: its ID goes in `_id`, its vector goes in your dense field, and its metadata keys become top-level fields. ### 4. Switch your application Point your application at the new index's host, and switch its calls to their [Documents API equivalents](#documents-api-equivalents). Writes sent to the old index after you loaded your data aren't in the new one, so pause them or replay them. ### 5. Delete the old index When you no longer need the old index, [delete it](/guides/indexes/manage-indexes#delete-an-index). ## Documents API equivalents Each legacy call has a Documents API equivalent. In the Python SDK: | Operation | Legacy vector index | Document index | | - | - | - | | Create | `pc.create_index(dimension=..., metric=..., vector_type=...)` | `pc.indexes.create(schema=...)` | | Write | `index.upsert` | `index.documents.upsert` | | Search | `index.query` with a vector | `index.documents.search` with a `dense_vector` clause in `score_by` | | Fetch | `index.fetch` | `index.documents.fetch` | | Update | `index.update` | `index.documents.update` | | Delete | `index.delete` | `index.documents.delete` | | List IDs | `index.list` | `index.documents.list` | For a legacy integrated index, see [Integrated embedding](/guides/search/integrated-embedding) for the document index setup, which needs Python SDK `10.1.0` or later: * `pc.create_index_for_model` becomes `pc.indexes.create` with a `string` field that declares `embed`. * `index.upsert_records` becomes `index.documents.upsert`. * `index.search` becomes `index.documents.search` with an `embed` clause in `score_by`. Index-management calls like `describe_index` and `list_indexes` also return a new shape on API version `2026-07`: * In the REST API, a `schema` object replaces the top-level `dimension`, `metric`, `vector_type`, and `spec`, so `dimension` and `metric` appear on the schema's dense-vector field. Update any code that calls the REST API directly. * The SDKs return both the new fields and the older top-level ones, so SDK code that reads the top-level fields keeps working. ## FAQ > [accordion] I use hybrid search (dense + sparse, legacy Vectors API). What happens? > > Your existing indexes that store both dense and sparse vectors keep working through the legacy Vectors API, with the same single combined query. On the Documents API, a schema can declare both a `dense_vector` and a `sparse_vector` field, so one index holds both, but a search ranks by one scoring type per request. There's no single combined dense + sparse query, so to combine results, run each search separately and fuse them client-side with [reciprocal rank fusion](/guides/search/reciprocal-rank-fusion). > [accordion] I use integrated embedding (the legacy Records API). Does anything change? > > Your existing indexes are unaffected, and the legacy Records API and `create_index_for_model` keep working. Document indexes support integrated embedding too: declare a `string` field with `embed` or `sparse_embed`, and Pinecone embeds its text for you. For new work, prefer that path. See [Integrated embedding](/guides/search/integrated-embedding). > [accordion] Can I keep creating indexes on the legacy Vectors API? > > Yes. In the `2026-07` SDK, your existing `create_index(dimension=..., metric=..., vector_type=..., spec=...)` code works unchanged and still creates a legacy vector index, so you don't have to downgrade. If you call the REST API directly on `2026-07`, use a schema with the reserved `_values`/`_sparse_values` fields, or pin an earlier API version (`X-Pinecone-Api-Version: 2026-04`) to send the original request body. Indexes you create either way stay on the `/vectors/*` data plane. # Processing locations Source: https://docs.pinecone.io/guides/indexes/processing-locations Learn where each hosted embedding and reranking model processes your text, and how to keep integrated embedding in the US. A model's processing location is where it processes the text you send it. Every hosted model uses one of two locations: * `global` means any of the provider's regions, including regions outside the United States. * `us` means only regions in the United States. Some models offer both, so you choose one with `processing_location` when you [declare an embedded field](/guides/search/integrated-embedding#declare-an-embedded-field). ## Locations by model The Processing location column of the [model gallery](/models/overview) lists each model's location. Currently only `text-embedding-3-small` and `text-embedding-3-large` let you choose, between `global` (the default) and `us`. `gemini-embedding-2` processes in `global` and accepts `processing_location` only when it's set to `global`. Every other model rejects it. The processing location doesn't follow your index's [cloud region](/guides/indexes/index-configuration#cloud-regions). An index in a region outside the US, such as `eu-west-1`, still defaults to `global`. On the Standard and Enterprise plans, it also accepts `us`. ## Set the processing location `processing_location` is a property of an embedded field on a document index, set on `embed` next to `dimension`, so it requires API version `2026-07`. One value covers both stored text and queries. To keep both in the US, set it to `us`: ```json US processing theme={null} { "chunk_text": { "type": "string", "embed": { "model": "text-embedding-3-large", "processing_location": "us" } } } ``` These rules apply: * The processing location is currently fixed at creation, like the rest of the embedding configuration. When you describe the index, the field's `embed.processing_location` shows the location the model uses now. * On the Starter and Builder plans, `text-embedding-3-small` and `text-embedding-3-large` are limited to `global`. On the Standard and Enterprise plans, you can set `processing_location` to `us`. * If your organization moves to the Builder plan, an index created with `us` keeps working but processes text in `global`, and describing or listing the index shows `global`. If you upgrade again, the index goes back to `us`. * An index created with `us` can't be kept when you [downgrade to the Starter plan](/admin/billing/downgrade-billing-plan#before-you-downgrade). Recreate it with `global` and re-upsert your data before you downgrade. * A location the model doesn't currently offer, such as `eu`, is rejected with a `400`. * The [List models](/reference/api/latest/inference/list-available-models) operation lists `processing_location`, with its accepted values, in a model's `supported_parameters` on API version `2026-07` and later. # Restore an index Source: https://docs.pinecone.io/guides/indexes/restore-an-index Restore a Pinecone serverless index from a backup into the same or a different region, and change the index name, tags, or deletion protection. ## 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/indexes/index-data-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/v7/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: 2026-07" \ -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" } ``` > [!TIP] > > You can create a serverless index from a backup using the [Pinecone console](https://app.pinecone.io/organizations/-/projects). ## Restore to a different region By default, [create index from backup](/reference/api/latest/control-plane/create_index_from_backup) creates the new index in the same cloud and region as the backup. To restore a serverless backup into a different region, set `deployment` to a `managed` deployment in the target region. The following rules apply: * The target region must be on the same cloud provider as the backup. Restoring to a different cloud provider isn't supported. * The backup must be in the current Pinecone project, and the new index is created in the same project. * A serverless backup can't be restored into a BYOC environment, and a BYOC backup can only be restored into the environment it was taken in. * In the Pinecone console, you can choose a different region only while the source index still exists. * Restoring to a different region incurs a cross-region transfer fee, charged per GB on top of the standard restore cost. The fee depends on the cloud provider and the backup's region. For details, see [Backups and restores](/guides/cost/understand-cost#backups-and-restores). For example, the following request restores a backup taken in the AWS `us-east-1` region into a new index in the AWS `us-west-2` region: ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); const response = await pc.backups.createIndex('a65ff585-d987-4da5-a622-72e19a6ed5f4', { name: 'restored-index', deployment: { deploymentType: 'managed', cloud: 'aws', region: 'us-west-2' }, }); console.log(response); ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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) } res, err := pc.CreateIndexFromBackup(ctx, &pinecone.CreateIndexFromBackupParams{ BackupId: "a65ff585-d987-4da5-a622-72e19a6ed5f4", Name: "restored-index", Deployment: &pinecone.IndexDeployment{ Managed: &pinecone.ManagedDeployment{Cloud: pinecone.CloudAWS, Region: "us-west-2"}, }, }) if err != nil { log.Fatalf("Failed to restore backup: %v", err) } fmt.Println(prettifyStruct(res)) } ``` ```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 "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "name": "restored-index", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-west-2" } }' ``` 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 isn't 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. > [!NOTE] > > 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 doesn't 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/v7/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: 2026-07" \ -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/v7/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: 2026-07" \ -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/indexes/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. > [!WARNING] > > **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: > [!NOTE] > > 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", grpc=True) ``` ```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(config, connection, "INDEX_NAME"); } } ``` ```go Go {21} theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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 an 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/v7/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: 2026-07" # Response: # { # "name": "docs-example-curl", # "host": "docs-example-curl-4zo0ijk.svc.aped-4627-b74a.pinecone.io", # "status": { # "ready": true, # "state": "Ready" # }, # "deployment": { # "deployment_type": "managed", # "region": "us-east-1", # "cloud": "aws", # "environment": "aped-4627-b74a" # }, # "read_capacity": { # "mode": "OnDemand", # "status": { # "state": "Ready", # "current_shards": null, # "current_replicas": null # } # }, # "schema": { # "fields": { # "chunk_text": { # "type": "string", # "description": null, # "full_text_search": { # "language": "en", # "stemming": false, # "stop_words": false # } # }, # "embedding": { # "type": "dense_vector", # "description": null, # "dimension": 1536, # "metric": "cosine" # } # } # }, # "deletion_protection": "disabled" # } ``` ## Target by index name This method is convenient for testing but isn't recommended for production: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.index(name="docs-example", grpc=True) ``` ```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) { 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. ``` # Choose a pod type and size Source: https://docs.pinecone.io/guides/legacy/pod-based-indexes/choose-a-pod-type-and-size Choose a Pinecone pod type and size (s1, p1, p2). Pod indexes are legacy and unavailable to new customers, and serverless needs no capacity planning. > [!WARNING] > > Pod-based indexes are legacy. Customers who signed up for a Standard or Enterprise plan on or after August 18, 2025 cannot create them. [Create a serverless index](/guides/indexes/create-an-index) instead. Serverless indexes use on-demand read capacity by default, or [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview) for sustained high query rates and workloads of millions of records or more. When planning your Pinecone deployment, it's 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/legacy/pod-based-indexes/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. > [!TIP] > > 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/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/indexes/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 doesn't 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/legacy/pod-based-indexes/understanding-pod-based-indexes#pod-types) of the index, the number of [replicas](/guides/legacy/pod-based-indexes/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/indexes/index-data-overview#p1-pods) are performance-optimized pods which provide very low query latencies, but hold fewer vectors per pod than [s1 pods](/guides/indexes/index-data-overview#s1-pods). They're 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're ideal for very large indexes with moderate or relaxed latency requirements. The [p2 pod type](/guides/indexes/index-data-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/legacy/pod-based-indexes/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/legacy/vectors-api/upsert-vectors#python-sdk-with-grpc) 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/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/legacy/pod-based-indexes/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/indexes/index-data-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's 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/legacy/pod-based-indexes/create-a-pod-based-index Create a Pinecone pod-based index. Pod indexes are legacy and unavailable to new customers, and serverless is the current option for new indexes. > [!WARNING] > > Pod-based indexes are legacy. Customers who signed up for a Standard or Enterprise plan on or after August 18, 2025 cannot create them. [Create a serverless index](/guides/indexes/create-an-index) instead. Serverless indexes use on-demand read capacity by default, or [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview) for sustained high query rates and workloads of millions of records or more. > [!NOTE] > > SDKs that target API version `2026-07` don't support creating pod-based indexes, and they reject creating an index from a collection. You can still list, describe, and delete existing collections. To create or restore a pod-based index, use an [SDK version](/reference/pinecone-sdks#sdk-versions) that targets an earlier API version, or send an earlier `X-Pinecone-Api-Version` with the REST API. To move a pod-based index to serverless, see [Migrate a pod-based index to serverless](/guides/legacy/pod-based-indexes/migrate-a-pod-based-index-to-serverless). This page shows you how to create a pod-based index. For guidance on serverless indexes, see [Create a serverless index](/guides/indexes/create-an-index). ## Create a pod index To create a pod index, use the [Create an 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/indexes/index-configuration#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/legacy/pod-based-indexes/understanding-pod-based-indexes#pod-types) and [size](/guides/indexes/index-data-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; 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", null, null, null, null, null, "disabled", null); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" // CreatePodIndex was removed in v7 (API version 2026-07). Use v6 to create pod-based indexes. "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) } 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", err) } 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/legacy/pod-based-indexes/restore-a-pod-based-index). # Manage pod-based indexes Source: https://docs.pinecone.io/guides/legacy/pod-based-indexes/manage-pod-based-indexes Manage Pinecone pod-based indexes. Pod indexes are legacy and unavailable to new customers, and serverless is recommended for new projects. > [!WARNING] > > Pod-based indexes are legacy. Customers who signed up for a Standard or Enterprise plan on or after August 18, 2025 cannot create them. [Create a serverless index](/guides/indexes/create-an-index) instead. Serverless indexes use on-demand read capacity by default, or [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview) for sustained high query rates and workloads of millions of records or more. This page shows you how to manage pod-based indexes. For guidance on serverless indexes, see [Manage serverless indexes](/guides/indexes/manage-indexes). ## Describe a pod-based index Use the [Describe an 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/v7/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 # } # } # } ``` > [!WARNING] > > **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 an index](/reference/api/latest/control-plane/delete_index) operation to delete a pod-based index and all of its associated resources. > [!NOTE] > > You are billed for a pod-based index even when it's not in use. ```python Python theme={null} # pip install pinecone 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/v7/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/indexes/manage-indexes#configure-deletion-protection). > [!TIP] > > 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's not needed for [filtering your queries](/guides/indexes/index-data-overview#metadata) and keep memory utilization low, specify which metadata fields to index using the `metadata_config` parameter. > [!NOTE] > > Since high-cardinality metadata doesn't cause high memory utilization in serverless indexes, selective metadata indexing isn't 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 don't 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.PodSpecMetadataConfig; import java.util.Arrays; import java.util.List; public class CreateIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); PodSpecMetadataConfig podSpecMetadataConfig = new PodSpecMetadataConfig(); List indexedItems = Arrays.asList("genre", "year"); podSpecMetadataConfig.setIndexed(indexedItems); pc.createPodsIndex("docs-example", 1536, "us-west1-gcp", "p1.x1", "cosine", null, null, null, podSpecMetadataConfig, null, "disabled", null); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" // CreatePodIndex was removed in v7 (API version 2026-07). Use v6 to create pod-based indexes. "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) } 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", MetadataConfig: podIndexMetadata, DeletionProtection: &deletionProtection, }) if err != nil { log.Fatalf("Failed to create pod-based index: %v", err) } 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 > [!NOTE] > > 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/indexes/create-an-index) or when [configuring an existing index](/guides/legacy/pod-based-indexes/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 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; 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", null, null, null, null, null, "enabled", null); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" // CreatePodIndex was removed in v7 (API version 2026-07). Use v6 to create pod-based indexes. "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) } 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", err) } 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; public class ConfigureIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.configurePodsIndex("docs-example", "enabled"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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; public class ConfigureIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.configurePodsIndex("docs-example", "disabled"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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 > [!NOTE] > > 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/indexes/index-data-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 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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) 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/indexes/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/indexes/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, 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/v7/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/indexes/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/indexes/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: 2026-07" \ -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/indexes/manage-indexes#configure-index-tags). ## Manage costs ### Set a project pod limit To control costs, [project owners](/admin/projects/projects-overview#project-roles) can set the maximum total number of pods allowed across all pod-based indexes in a project. The default pod limit is 5. > [tab] Pinecone console > > 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**. > [tab] API > > > > ```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 isn't in use, [back it up using collections](/guides/legacy/pod-based-indexes/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/legacy/pod-based-indexes/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/legacy/pod-based-indexes/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. > [!NOTE] > > For pod-based indexes, project owners can [set limits for the total number of pods](/guides/legacy/pod-based-indexes/manage-pod-based-indexes#set-a-project-pod-limit) 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). > [!NOTE] > > This feature is available on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). ### Use Prometheus > [!NOTE] > > 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/legacy/pod-based-indexes/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/legacy/pod-based-indexes/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/architecture). The migration process is free; the standard costs of upserting records to a new serverless index aren't applied. > [!WARNING] > > 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/optimize/dedicated-read-nodes/overview). > > Before migrating, [contact Pinecone Support](/admin/support/contact-support) for help estimating and managing cost implications. ## Limitations Migration is supported for pod-based indexes with up to 500 million records and 20,000 namespaces across all supported clouds (AWS, GCP, and Azure). If your index has more than 500 million records, [contact Pinecone Support](/admin/support/contact-support) before you migrate. After you migrate, note that serverless indexes don't support the following features: * [Selective metadata indexing](/guides/legacy/pod-based-indexes/manage-pod-based-indexes#selective-metadata-indexing) * Because high-cardinality metadata in serverless indexes doesn't cause high memory utilization, this operation isn't relevant. * [Filtering index statistics by metadata](/reference/api/latest/data-plane/describeindexstats) If you were using either feature with your pod-based index, you'll need to adapt your code. If you're blocked by these limitations, [contact Pinecone Support](/admin/support/contact-support). ## How it works Migrating a pod-based index to serverless is a 2-step process: **1. Save the pod-based index as a collection** **2. Create a new serverless index from the collection** 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](/admin/support/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/data/upsert-data), [updates](/guides/data/update-data), and [deletes](/guides/data/delete-data) to the pod-based index won't 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 > [tab] Pinecone console > > 1. In the [Pinecone console](https://app.pinecone.io/), go to your pod-based index and click the **ellipsis (...) menu > Migrate to serverless**. > > ![](https://mintcdn.com/pinecone/r0TaYXrfSrAYZYUj/images/migrate-to-serverless.png?fit=max\&auto=format\&n=r0TaYXrfSrAYZYUj\&q=85\&s=24217a2e791ffce162686b8fdef47948) > > > [!NOTE] > > > > The dropdown won't 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](https://mintcdn.com/pinecone/9qvQp5nU6duJvusQ/images/create-serverless-from-collection-initializing.png?fit=max\&auto=format\&n=9qvQp5nU6duJvusQ\&q=85\&s=acffe738f1cbe2e08e4bc2fad7e957dd) > > When the new serverless index is ready, the status will change to green: > > ![create index from collection - ready status](https://mintcdn.com/pinecone/9qvQp5nU6duJvusQ/images/create-serverless-from-collection-ready.png?fit=max\&auto=format\&n=9qvQp5nU6duJvusQ\&q=85\&s=e04b6b0d892301435be282e5c4fa394b) > [tab] API/SDK > > 1. Use the [Create a 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 an index](/reference/api/2026-04/control-plane/create_index) operation to create a new serverless index from the collection: > > * Use API version `2025-04` or later. Creating a serverless index from a collection isn't supported in earlier versions. > * Set `dimension` to the same dimension as the pod-based index. Changing the dimension isn't supported. > * Set `cloud` to the cloud where the pod-based index is hosted. Migrating to a different cloud isn't 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 --upgrade ``` ```JavaScript JavaScript theme={null} npm install @pinecone-database/pinecone@latest ``` ```shell Java theme={null} # Maven io.pinecone pinecone-client 6.3.0 # Gradle implementation "io.pinecone:pinecone-client:6.3.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. > [!WARNING] > > 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/indexes/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/v7/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: 2026-07" ``` > [!NOTE] > > On API version `2026-07`, the `curl` response returns `deployment`, `read_capacity`, and `schema` objects in place of the top-level `dimension`, `metric`, `vector_type`, and `spec`. The SDKs return both the new fields and the older top-level ones for backward compatibility. See [Move to the Documents API](/guides/indexes/move-to-the-documents-api) for details. 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", "host": "docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io", "status": { "ready": true, "state": "Ready" }, "deployment": { "deployment_type": "managed", "region": "us-east-1", "cloud": "aws", "environment": "aped-4627-b74a" }, "read_capacity": { "mode": "OnDemand", "status": { "state": "Ready", "current_shards": null, "current_replicas": null } }, "schema": { "fields": { "sparse_embedding": { "type": "sparse_vector", "description": null } } }, "tags": { "environment": "development" }, "deletion_protection": "disabled" }, { "name": "docs-example-dense", "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io", "status": { "ready": true, "state": "Ready" }, "deployment": { "deployment_type": "managed", "region": "us-east-1", "cloud": "aws", "environment": "aped-4627-b74a" }, "read_capacity": { "mode": "OnDemand", "status": { "state": "Ready", "current_shards": null, "current_replicas": null } }, "schema": { "fields": { "chunk_text": { "type": "string", "description": null, "full_text_search": { "language": "en", "stemming": false, "stop_words": false } }, "embedding": { "type": "dense_vector", "description": null, "dimension": 1536, "metric": "cosine" } } }, "tags": { "environment": "development" }, "deletion_protection": "disabled" } ] } ``` 3. [Describing an index](/guides/indexes/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/v7/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: 2026-07" ``` ## 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(name="YOUR_SERVERLESS_INDEX_NAME", grpc=True) ``` ```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/indexes/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/indexes/manage-indexes#delete-an-index) to avoid paying for unused resources. > [!WARNING] > > 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/architecture) * [Understanding serverless cost](/guides/cost/understand-cost) # Understanding pod-based indexes Source: https://docs.pinecone.io/guides/legacy/pod-based-indexes/understanding-pod-based-indexes Understand Pinecone pod-based indexes, including pod types and sizing. Pod indexes are legacy and unavailable to new customers, and serverless is recommended. > [!WARNING] > > Pod-based indexes are legacy. Customers who signed up for a Standard or Enterprise plan on or after August 18, 2025 cannot create them. [Create a serverless index](/guides/indexes/create-an-index) instead. Serverless indexes use on-demand read capacity by default, or [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview) for sustained high query rates and workloads of millions of records or more. 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/legacy/pod-based-indexes/choose-a-pod-type-and-size) for your dataset and workload. ## Pod types Different pod types are priced differently. See [Understand Pinecone cost](/guides/cost/understand-cost) for more details. > [!NOTE] > > Once a pod-based index is created, you can't 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/legacy/pod-based-indexes/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're 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're 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 doesn't 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/legacy/pod-based-indexes/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/indexes/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 can't 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. > [accordion] Example > > 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/legacy/pod-based-indexes/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/indexes/index-data-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/indexes/back-up-an-index#pod-based-index-backups-using-collections) * You can't 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/legacy/vectors-api/hybrid-search-single-index) * Only `s1` and `p1` [pod-based indexes](/guides/legacy/pod-based-indexes/understanding-pod-based-indexes#pod-types) using the dotproduct distance metric support sparse-dense vectors. # Create a legacy integrated index Source: https://docs.pinecone.io/guides/legacy/records-api/create-an-integrated-index Create a legacy integrated index with create_index_for_model, so Pinecone embeds source text with a hosted model through the legacy Records API. > [!NOTE] > > New projects should use the [Documents API](/guides/get-started/documents-api). To move an existing index, see [Move to the Documents API](/guides/indexes/move-to-the-documents-api). A legacy integrated index is created with `create_index_for_model` and served by the legacy Records API. Pinecone converts the source text you upsert and search with to vectors, using one hosted embedding model per index. To have Pinecone embed text in a document index instead, declare `embed` or `sparse_embed` on a `string` field. See [Integrated embedding](/guides/search/integrated-embedding). > [!NOTE] > > Legacy integrated indexes (created with `create_index_for_model` and served by the legacy Records API) don't support [updating](/guides/data/update-data) or [importing](/guides/data/import-data) with text. ## Dense embedding 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/indexes/index-configuration#cloud-regions) where the index should be deployed. * Set `embed.model` to one of [Pinecone's hosted embedding models](/guides/indexes/index-configuration#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 [Create an index with integrated embedding](/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.CreateIndexForModelRequestEmbed; 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, "aws", region, embed, "disabled", tags ); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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.CloudAWS, 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", err) } 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: 2026-07" \ -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" ``` ## Sparse 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/indexes/index-configuration#cloud-regions) where the index should be deployed. * Set `embed.model` to one of [Pinecone's hosted sparse embedding models](/guides/indexes/index-configuration#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 [Create an index with integrated embedding](/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.CreateIndexForModelRequestEmbed; 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, "aws", region, embed, "disabled", tags ); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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.CloudAWS, 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", err) } 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: 2026-07" \ -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" ``` ## Wait for the index to be ready A new index can't accept data until its `status.ready` field is `true`. See [Wait for the index to be ready](/guides/indexes/create-an-index#wait-for-the-index-to-be-ready). # Search a legacy integrated index with text Source: https://docs.pinecone.io/guides/legacy/records-api/search-with-text Search a legacy integrated index with query text through the legacy Records API, with dense or sparse embedding and optional metadata filters. > [!NOTE] > > New projects should use the [Documents API](/guides/get-started/documents-api). To move an existing index, see [Move to the Documents API](/guides/indexes/move-to-the-documents-api). This page shows you how to search a legacy integrated index created with `create_index_for_model`. The legacy Records API converts the query text to a vector with the embedding model associated with the index. For a document index with [integrated embedding](/guides/search/integrated-embedding), see [Semantic search](/guides/search/semantic-search) and [Sparse-vector search](/guides/search/sparse-vector-search). ## Search with dense embedding To search a legacy integrated index with query text, use the [Search with text](/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, the `fields` to return in the response. If you don't specify any, the response includes all fields. For example, the following code searches for the 2 records most semantically related to the query text "Disease prevention": ```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/indexes/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/indexes/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/indexes/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/v7/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/indexes/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.Println(prettifyStruct(res)) } ``` ```bash 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: 2026-07" \ -d '{ "query": { "inputs": {"text": "Disease prevention"}, "top_k": 2 }, "fields": ["category", "chunk_text"] }' ``` In the response, each record has a similarity score that represents its distance to the query vector, calculated according to the index's [similarity metric](/guides/indexes/index-configuration#similarity-metrics): ```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 sparse embedding To search a legacy integrated index with query text, use the [Search with text](/reference/api/latest/data-plane/search_records) operation with the following parameters: * `namespace`: The [namespace](/guides/indexes/index-data-overview#namespaces) to query. To use the default namespace, set to `"__default__"`. * `query.inputs.text`: The query text. Pinecone uses the [embedding model](/guides/indexes/index-configuration#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/indexes/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/indexes/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/indexes/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("quarter"); 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/v7/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/indexes/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", "quarter"}, }) if err != nil { log.Fatalf("Failed to search records: %v", err) } fmt.Println(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: 2026-07" \ -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 look like this. 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=AAPL'''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 } } ``` ### Filter by required terms > [!NOTE] > > This feature is in [public preview](/release-notes/feature-availability). See [limitations](#limitations) for details. When searching a legacy integrated index with text, you can specify a list of terms that must be present in each sparse-vector 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. `all` is the only supported strategy: every term 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: 2026-07" \ -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 * **Legacy integrated indexes only**: Filtering by required terms is supported only for legacy integrated indexes that use [`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0). In a document index, use a [`$match_all` filter](/guides/search/filter-by-metadata#text-match-filters) instead. * **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. ## 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`. For the supported operators, see [Metadata filter expressions](/guides/search/filter-by-metadata#metadata-filter-expressions). ```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/indexes/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/indexes/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/indexes/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/v7/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/indexes/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: 2026-07" \ -d '{ "query": { "inputs": {"text": "Disease prevention"}, "top_k": 3, "filter": {"category": "digestive system"} }, "fields": ["category", "chunk_text"] }' ``` # Upsert text into a legacy integrated index Source: https://docs.pinecone.io/guides/legacy/records-api/upsert-text Upsert source text into a legacy integrated index with the legacy Records API, and have Pinecone convert it to dense or sparse vectors. > [!NOTE] > > New projects should use the [Documents API](/guides/get-started/documents-api). To move an existing index, see [Move to the Documents API](/guides/indexes/move-to-the-documents-api). This page shows you how to upsert source text into a legacy integrated index created with `create_index_for_model`. The legacy Records API converts the text to vectors with the hosted embedding model associated with the index. For a document index with [integrated embedding](/guides/search/integrated-embedding), see [Upsert data](/guides/data/upsert-data). When you describe a legacy integrated index, its text field has the `semantic_text` type. Document schemas don't use that type. ## Upsert text as dense vectors To upsert source text into a legacy integrated index, use the [Upsert text](/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/indexes/index-data-overview#namespaces) to upsert into. If the namespace doesn't exist, it's 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/indexes/index-data-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/indexes/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( namespace="example-namespace", records=[ { "_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/indexes/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({ records: [ { "_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" "log" "github.com/pinecone-io/go-pinecone/v7/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/indexes/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/indexes/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: 2026-07" \ -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"}' ``` ## Upsert text as sparse vectors To upsert source text into a legacy integrated index, use the [Upsert text](/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/indexes/index-data-overview#namespaces) to upsert into. If the namespace doesn't exist, it's 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/indexes/index-data-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} import time 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/indexes/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( namespace="example-namespace", records=[ { "_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/indexes/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({ records: [ { "_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" "log" "github.com/pinecone-io/go-pinecone/v7/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/indexes/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: 2026-07" \ -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" }' ``` # Create a legacy vector index Source: https://docs.pinecone.io/guides/legacy/vectors-api/create-a-vector-index Create a legacy vector index that stores dense or sparse vectors you generate with an external embedding model, served by the legacy Vectors API. > [!NOTE] > > New projects should use the [Documents API](/guides/get-started/documents-api). To move an existing index, see [Move to the Documents API](/guides/indexes/move-to-the-documents-api). A legacy vector index stores dense or sparse vectors that you generate with an external embedding model, and it's read and written through the legacy Vectors API. To store vectors in a document index instead, declare a `dense_vector` or `sparse_vector` field. See [Create a document index](/guides/indexes/create-an-index#create-a-document-index). ## Dense vectors If you use an external embedding model to convert your data to dense vectors, [create an index](/reference/api/2026-04/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/indexes/index-configuration#cloud-regions) where the index should be deployed. For Python, you also need to import the `ServerlessSpec` class. Other parameters are optional. See [Create an index](/reference/api/2026-04/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 java.util.HashMap; import java.util.Map; 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"; Map tags = new HashMap<>(); tags.put("environment", "development"); pc.createServerlessIndex( indexName, "cosine", 1536, cloud, region, "disabled", tags ); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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.IndexMetricCosine deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: indexName, VectorType: &vectorType, Dimension: &dimension, Metric: &metric, Cloud: pinecone.CloudAWS, 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: 2026-07" \ -d '{ "name": "standard-dense-curl", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "_values": { "type": "dense_vector", "dimension": 1536, "metric": "cosine" } } }, "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" ``` ## Sparse vectors If you use an external embedding model to convert your data to sparse vectors, [create an index](/reference/api/2026-04/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 don't support other [distance metrics](/guides/indexes/index-data-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 [Create an index](/reference/api/2026-04/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 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, "disabled", tags, vectorType); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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.IndexMetricDotproduct deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: indexName, Metric: &metric, VectorType: &vectorType, Cloud: pinecone.CloudAWS, 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: 2026-07" \ -d '{ "name": "standard-sparse-curl", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "_sparse_values": { "type": "sparse_vector" } } } }' ``` ```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" ``` ## Wait for the index to be ready A new index can't accept data until its `status.ready` field is `true`. See [Wait for the index to be ready](/guides/indexes/create-an-index#wait-for-the-index-to-be-ready). # Delete vectors from a legacy vector index Source: https://docs.pinecone.io/guides/legacy/vectors-api/delete-vectors Delete records from a legacy vector index by ID or metadata filter with the legacy Vectors API, or delete every record in a namespace. > [!NOTE] > > New projects should use the [Documents API](/guides/get-started/documents-api). To move an existing index, see [Move to the Documents API](/guides/indexes/move-to-the-documents-api). This page shows you how to delete records from a namespace in a legacy vector index with the legacy Vectors API. For a document index, see [Delete data](/guides/data/delete-data). ## 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. > [!NOTE] > > To remove records from the default namespace, specify `"__default__"` as the namespace in your request. ```Python Python theme={null} # pip install pinecone 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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) 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/indexes/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/indexes/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, 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/v7/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/indexes/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/indexes/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-07" \ -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/indexes/index-data-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 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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) 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/indexes/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/indexes/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, 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/v7/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/indexes/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/indexes/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: 2026-07" \ -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 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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) 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/indexes/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/indexes/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "INDEX_NAME"); index.deleteAll("example-namespace"); } } ``` ```go Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v7/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/indexes/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/indexes/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-07" \ -d '{ "deleteAll": true, "namespace": "example-namespace" } ' ``` ## 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 | 20 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/data/check-data-freshness). # Fetch vectors from a legacy vector index Source: https://docs.pinecone.io/guides/legacy/vectors-api/fetch-vectors Fetch records from a legacy vector index by ID or metadata filter with the legacy Vectors API to inspect their vector values and metadata. > [!NOTE] > > New projects should use the [Documents API](/guides/get-started/documents-api). To move an existing index, see [Move to the Documents API](/guides/indexes/move-to-the-documents-api). This page shows you how to fetch records from a namespace in a legacy vector index with the legacy Vectors API. For a document index, see [Fetch data](/guides/data/fetch-data). Pinecone stores vector values as 32-bit floats, so fetched values can differ slightly from high-precision values you upserted. ## 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/indexes/index-data-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. > [!NOTE] > > 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 [Search with a vector](/reference/api/latest/data-plane/query) operation instead, with `include_values` left at its default of `false`. 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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) 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/indexes/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/indexes/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, 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/v7/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/indexes/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/indexes/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-07" ``` 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/indexes/index-data-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/indexes/index-data-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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) 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/indexes/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/indexes/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, 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/v7/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/indexes/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/indexes/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-07" \ -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: 2026-07" \ -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 doesn't 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/data/check-data-freshness). # Run hybrid search on two legacy vector indexes Source: https://docs.pinecone.io/guides/legacy/vectors-api/hybrid-search-separate-indexes Store dense and sparse vectors in two Pinecone indexes linked by ID, query each, and merge the results client-side with reciprocal rank fusion. > [!NOTE] > > New projects should use the [Documents API](/guides/get-started/documents-api). To move an existing index, see [Move to the Documents API](/guides/indexes/move-to-the-documents-api). Store dense and sparse vectors in two separate Pinecone indexes linked by a shared record ID, query each index, and merge the results client-side (for example, with [reciprocal rank fusion](/guides/search/reciprocal-rank-fusion)). This is the legacy Vectors API separate-index hybrid pattern. It's more flexible than a single index (it supports sparse-only queries, integrated embedding, and per-index reranking) but requires managing two indexes. ## Set up and search To perform hybrid search with separate indexes, follow these steps: **1. Create the indexes** [Create one index for dense vectors](/guides/legacy/vectors-api/create-a-vector-index#dense-vectors) and [another for sparse vectors](/guides/legacy/vectors-api/create-a-vector-index#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"} } ) ``` **2. Upsert dense and sparse vectors** [Upsert dense vectors](/guides/legacy/vectors-api/upsert-vectors#upsert-dense-vectors) and [upsert sparse vectors](/guides/legacy/vectors-api/upsert-vectors#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/indexes/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(namespace="example-namespace", records=records) sparse_index.upsert_records(namespace="example-namespace", records=records) ``` **3. Search by dense vectors** 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}} ``` **4. Search by sparse vectors** Perform a [sparse-vector search](/guides/search/sparse-vector-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}} ``` **5. Merge and deduplicate the results** Merge the 40 dense and 40 sparse results and deduplicate 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.'} ] ``` **6. Rerank the results** 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. ``` # Run hybrid search on a legacy vector index Source: https://docs.pinecone.io/guides/legacy/vectors-api/hybrid-search-single-index Run hybrid search on one Pinecone index storing a dense and a sparse vector per record, weighting the two signals client-side with an alpha value. > [!NOTE] > > New projects should use the [Documents API](/guides/get-started/documents-api). To move an existing index, see [Move to the Documents API](/guides/indexes/move-to-the-documents-api). Store a dense vector and a sparse vector on each record in a single Pinecone index, then query both signals in one request. Pinecone combines them server-side. Because sparse (BM25-style) scores are unbounded, you set the balance between the two signals client-side, by scaling the query vectors before the request (an `alpha` weighting). This is the legacy Vectors API single-index hybrid pattern. ## Normalize sparse and dense values A single index that stores both vector types doesn't reconcile their score ranges. Dense-vector scores fall in a bounded range (roughly `[-1, 1]` for `dotproduct` on unit-norm embeddings), while BM25-style sparse weights are unbounded and 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 keyword). * `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`](#hybrid-single-5-alpha) 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) — a 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. ## Set up and search To perform hybrid search with a single index that stores both dense and sparse vectors, follow these steps: **1. Create the index** To store both dense and sparse vectors in a single index, use the [Create an index](/reference/api/2026-04/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" ) ) ``` **2. Generate vectors** Use Pinecone's [hosted embedding models](/guides/indexes/index-configuration#embedding-models) to [convert data into dense and sparse vectors](/reference/api/latest/inference/generate-vectors). ```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"} ) ``` **3. Upsert records with dense and sparse vectors** Use the [Upsert records](/reference/api/latest/data-plane/upsert) operation, specifying dense values in the `value` parameter and sparse values in the `sparse_values` parameter. > [!NOTE] > > Only indexes that store dense vectors with the [dotproduct distance metric](/guides/indexes/index-data-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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) # 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" ) ``` **4. Search the index** Use the [Generate vectors](/reference/api/latest/inference/generate-vectors) operation to convert your query into a dense vector and a sparse vector, and then use the [Search with a vector](/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}} ``` **5. Search the index with explicit weighting** 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 doesn't 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 ) ``` # Import vectors into a legacy vector index Source: https://docs.pinecone.io/guides/legacy/vectors-api/import-vectors Prepare Parquet files to bulk import dense, sparse, or hybrid vectors from object storage into a legacy vector index. > [!NOTE] > > New projects should use the [Documents API](/guides/get-started/documents-api). To move an existing index, see [Move to the Documents API](/guides/indexes/move-to-the-documents-api). > [!NOTE] > > This feature is available on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). A legacy vector index imports Parquet files from object storage. Follow the steps in [Import data](/guides/data/import-data) to create an index, add a storage integration, lay out one directory per namespace, and start the import. This page covers the Parquet file format for each kind of legacy vector index. You can also import Parquet files into a legacy integrated index, but its records must contain vectors, not text. To add text that Pinecone embeds, use [Upsert text](/guides/legacy/records-api/upsert-text). ## Parquet file format > [tab] Dense vectors > > To import into a namespace in an [index of dense vectors](/guides/indexes/index-data-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/key-terms#record-id). | > | `values` | `LIST` | Required. A list of floating-point values that make up the [dense vector embedding](/guides/get-started/key-terms#dense-vector). | > | `metadata` | `STRING` | Optional. Additional [metadata](/guides/get-started/key-terms#metadata) for each record. To omit from specific rows, use `NULL`. | > > > [!NOTE] > > > > 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 ..."} > ``` > [tab] Sparse vectors > > To import into a namespace in an [index of sparse vectors](/guides/indexes/index-data-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/key-terms#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/key-terms#sparse-vector). | > | `metadata` | `STRING` | Optional. Additional [metadata](/guides/get-started/key-terms#metadata) for each record. To omit from specific rows, use `NULL`. | > > > [!NOTE] > > > > 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 ..."} > ``` > [tab] Dense + sparse > > To import into a namespace in an [index with both dense and sparse vectors](/guides/legacy/vectors-api/hybrid-search-single-index), 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/key-terms#record-id). | > | `values` | `LIST` | Required. A list of floating-point values that make up the [dense vector embedding](/guides/get-started/key-terms#dense-vector). | > | `sparse_values` | `STRUCT, values: LIST>` | Optional. A list of floating-point values that make up the [sparse vector embedding](/guides/get-started/key-terms#sparse-vector). To omit from specific rows, use `NULL`. | > | `metadata` | `STRING` | Optional. Additional [metadata](/guides/get-started/key-terms#metadata) for each record. To omit from specific rows, use `NULL`. | > > > [!NOTE] > > > > 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 ..."} > ``` # List vector IDs in a legacy vector index Source: https://docs.pinecone.io/guides/legacy/vectors-api/list-vector-ids List the IDs of records in a namespace of a legacy vector index with the legacy Vectors API, filter by ID prefix, and paginate. > [!NOTE] > > New projects should use the [Documents API](/guides/get-started/documents-api). To move an existing index, see [Move to the Documents API](/guides/indexes/move-to-the-documents-api). This page shows you how to list record IDs in a namespace of a legacy vector index with the legacy Vectors API. For a document index, see [List IDs](/guides/data/list-record-ids). > [!NOTE] > > 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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) 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/indexes/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/indexes/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, 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/v7/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/indexes/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/indexes/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: 2026-07" # 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/indexes/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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) 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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) 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/indexes/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/indexes/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, 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/v7/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/indexes/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/indexes/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: 2026-07" # 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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) 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/v7/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/indexes/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/indexes/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: 2026-07" # 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 doesn't 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", grpc=True) 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/v7/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/indexes/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: 2026-07" # Response: # { # "vectors": [ # { "id": "doc3#chunk1" }, # { "id": "doc5#chunk2" }, # { "id": "doc5#chunk3" }, # { "id": "doc5#chunk4" }, # ... # ], # "namespace": "example-namespace", # "usage": { # "readUnits": 1 # } # } ``` # Manage chunked records in a legacy index Source: https://docs.pinecone.io/guides/legacy/vectors-api/manage-chunked-records Fetch, search, delete, and replace all chunks of a source document in a legacy vector index using ID prefixes and a document_id metadata field. > [!NOTE] > > New projects should use the [Documents API](/guides/get-started/documents-api). To move an existing index, see [Move to the Documents API](/guides/indexes/move-to-the-documents-api). When you split a long source document into chunks, each chunk is stored as its own record in a legacy vector index. To work with all of a source document's chunks at once, give each chunk a [structured ID](/guides/indexes/data-modeling#use-structured-ids) prefixed with the source document's ID, and a `document_id` metadata field. The code on this page assumes you generate the vectors yourself. For a document index, see [Manage document chunks](/guides/data/manage-document-chunks). > [!NOTE] > > Pinecone is [eventually consistent](/guides/data/check-data-freshness), so a read right after a write (upsert, update, or delete) may not return the latest data. If you need to read immediately after writing, add a short delay or [retry logic](/guides/production/error-handling#implement-retry-logic). ## Upsert chunks [Upsert](/guides/legacy/vectors-api/upsert-vectors) each chunk with its structured ID and `document_id`, plus any other metadata you want to filter on or display: ```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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) # Replace with each chunk's embedding, which must match the index's dimension (1536 in this example) chunk1_vector = [0.1, 0.2] * 768 chunk2_vector = [0.2, 0.1] * 768 chunk3_vector = [0.3, 0.1] * 768 index.upsert( namespace="example-namespace", vectors=[ { "id": "document1#chunk1", "values": chunk1_vector, "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": chunk2_vector, "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": chunk3_vector, "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 within a document To search only one source document's chunks, add a [metadata filter](/guides/search/filter-by-metadata#metadata-filter-expressions) on `document_id`: ```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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) # Replace with your query embedding, which must match the index's dimension (1536 in this example) query_vector = [0.1, 0.2] * 768 filtered_results = index.query( namespace="example-namespace", vector=query_vector, top_k=3, filter={ "document_id": {"$eq": "document1"} }, include_metadata=True, include_values=False ) print(filtered_results) ``` ## Fetch all chunks of a document To retrieve all of a source document's chunks, [list](/guides/legacy/vectors-api/list-vector-ids) their IDs by prefix, and then [fetch](/guides/legacy/vectors-api/fetch-vectors) them: ```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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) # List all chunks for document1 using ID prefix. # Each iteration yields one page of IDs. chunk_ids = [] for page in index.list(prefix='document1#', namespace='example-namespace'): chunk_ids.extend(item.id for item in page.vectors) 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 ``` ## Delete chunks To [delete](/guides/legacy/vectors-api/delete-vectors) some or all of a source document's chunks, filter on their 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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) # 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"} } ) ``` ## Replace a chunked document When the number or order of a source document's chunks changes, delete all of its chunks with a metadata filter, and then upsert the new ones. To change one chunk's content without changing the chunk count, [update](/guides/legacy/vectors-api/update-vectors) it by ID instead. ```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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) # 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 # Replace with each chunk's embedding, which must match the index's dimension (1536 in this example) chunk1_vector = [0.1, 0.2] * 768 chunk2_vector = [0.2, 0.1] * 768 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") ``` # Query a legacy vector index Source: https://docs.pinecone.io/guides/legacy/vectors-api/query-vectors Query a legacy vector index with the legacy Vectors API, using a dense vector, a sparse vector, or a record ID, with optional metadata filters. > [!NOTE] > > New projects should use the [Documents API](/guides/get-started/documents-api). To move an existing index, see [Move to the Documents API](/guides/indexes/move-to-the-documents-api). This page shows you how to query a legacy vector index with the legacy Vectors API. For a document index, see [Semantic search](/guides/search/semantic-search), [Sparse-vector search](/guides/search/sparse-vector-search), and [Filter by metadata](/guides/search/filter-by-metadata). ## Query with dense vectors In a legacy vector index, the query is either a dense vector or the ID of a record whose vector Pinecone uses as the query. ### Query with a dense vector To search with a dense vector representation of a query, use the [Search with a vector](/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, set `include_values`, `include_metadata`, or both to `true` to include the vector values, metadata, or both for 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-namespace` 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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) # Replace with your query embedding, which must match the index's dimension (1536 in this example) query_vector = [0.1] * 1536 index.query( namespace="example-namespace", vector=query_vector, 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/indexes/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") // Replace with your query embedding, which must match the index's dimension (1536 in this example) const queryVector = new Array(1536).fill(0.1); const queryResponse = await index.namespace('example-namespace').query({ vector: queryVector, 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.Collections; 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/indexes/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "INDEX_NAME"); // Replace with your query embedding, which must match the index's dimension (1536 in this example) List query = Collections.nCopies(1536, 0.1f); 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/v7/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/indexes/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) } // Replace with your query embedding, which must match the index's dimension (1536 in this example) queryVector := make([]float32, 1536) for i := range queryVector { queryVector[i] = 0.1 } 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.Println(prettifyStruct(res)) } } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" # Stand-in built with jq. Replace with your query embedding, which must match the index's dimension (1536 in this example) QUERY_VECTOR=$(jq -nc '[range(1536) | 0.1]') curl "https://$INDEX_HOST/query" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "vector": '"$QUERY_VECTOR"', "namespace": "example-namespace", "topK": 3, "includeMetadata": true, "includeValues": false }' ``` In the response, each record has a similarity score that represents its distance to the query vector, calculated according to the index's [similarity metric](/guides/indexes/index-configuration#similarity-metrics): ```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 } } ``` ### Query with a record ID When you search with a record ID, Pinecone uses the dense vector associated with the record as the query. Because search is approximate, the results aren't guaranteed to include that record, even with a high `top_k`. To retrieve a specific record, [fetch it by ID](/guides/legacy/vectors-api/fetch-vectors#fetch-records-by-id). To search with a record ID, use the [Search with a vector](/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, set `include_values`, `include_metadata`, or both to `true` to include the vector values, metadata, or both for 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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) 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/indexes/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/indexes/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "INDEX_NAME"); QueryResponseWithUnsignedIndices queryResponse = 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/v7/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/indexes/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.Println(prettifyStruct(res.Matches)) } } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/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: 2026-07" \ -d '{ "id": "rec2", "namespace": "example-namespace", "topK": 3, "includeMetadata": true, "includeValues": false }' ``` ## Query with sparse vectors In a legacy vector index, the query is either a sparse vector or the ID of a record whose sparse vector Pinecone uses as the query. ### Query with a sparse vector To search an index of sparse vectors with a sparse vector representation of a query, use the [Search with a vector](/reference/api/latest/data-plane/query) operation with the following parameters: * `namespace`: The [namespace](/guides/indexes/index-data-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`. > [!NOTE] > > 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/indexes/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/indexes/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, 4283091697L); 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/v7/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/indexes/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.Println(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: 2026-07" \ -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": 3, "includeMetadata": true, "includeValues": false }' ``` The results look like this. 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 } } ``` ### Query 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 [Search with a vector](/reference/api/latest/data-plane/query) operation with the following parameters: * `namespace`: The [namespace](/guides/indexes/index-data-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`. > [!NOTE] > > 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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) 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/indexes/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/indexes/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "INDEX_NAME"); QueryResponseWithUnsignedIndices queryResponse = 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/v7/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/indexes/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.Println(prettifyStruct(res.Matches)) } } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/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: 2026-07" \ -d '{ "id": "rec2", "namespace": "example-namespace", "topK": 3, "includeMetadata": true, "includeValues": false }' ``` ## Query with a metadata filter The following code queries for the 3 records that are most semantically similar to a query vector and that have a `category` metadata field with the value `digestive system`. For the supported operators, see [Metadata filter expressions](/guides/search/filter-by-metadata#metadata-filter-expressions). ```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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) # Replace with your query embedding, which must match the index's dimension (1536 in this example) query_vector = [0.1] * 1536 index.query( namespace="example-namespace", vector=query_vector, 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/indexes/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") // Replace with your query embedding, which must match the index's dimension (1536 in this example) const queryVector = new Array(1536).fill(0.1); const queryResponse = await index.namespace('example-namespace').query({ vector: queryVector, 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.Collections; 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/indexes/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "INDEX_NAME"); // Replace with your query embedding, which must match the index's dimension (1536 in this example) List query = Collections.nCopies(1536, 0.1f); 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(3, 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/v7/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/indexes/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) } // Replace with your query embedding, which must match the index's dimension (1536 in this example) queryVector := make([]float32, 1536) for i := range queryVector { queryVector[i] = 0.1 } 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/indexes/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" # Stand-in built with jq. Replace with your query embedding, which must match the index's dimension (1536 in this example) QUERY_VECTOR=$(jq -nc '[range(1536) | 0.1]') curl "https://$INDEX_HOST/query" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "vector": '"$QUERY_VECTOR"', "namespace": "example-namespace", "topK": 3, "filter": {"category": {"$eq": "digestive system"}}, "includeMetadata": true, "includeValues": false }' ``` # Update vectors in a legacy vector index Source: https://docs.pinecone.io/guides/legacy/vectors-api/update-vectors Update a record's metadata or vector values by ID, or update metadata across records with a filter, in a legacy vector index. > [!NOTE] > > New projects should use the [Documents API](/guides/get-started/documents-api). To move an existing index, see [Move to the Documents API](/guides/indexes/move-to-the-documents-api). This page shows you how to update records in a namespace of a legacy vector index with the legacy Vectors API. To replace whole records, [upsert](/guides/legacy/vectors-api/upsert-vectors) them instead. For a document index, see [Update data](/guides/data/update-data). ## Update by ID To update the vector and/or metadata of a single record, use the [Update a record](/reference/api/latest/data-plane/update) operation with the following parameters: * `namespace`: The [namespace](/guides/indexes/index-data-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 doesn't exist, it's added. > [!WARNING] > > 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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) 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/indexes/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/indexes/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, 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/v7/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/indexes/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/indexes/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: 2026-07" \ -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/indexes/index-data-overview#namespaces) containing the records to update. To use the default namespace, set this to `"__default__"`. * `filter`: A [metadata filter expression](/guides/indexes/index-data-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 doesn't exist, it is added. * `dry_run`: Optional. If `true`, the number of records that match the filter expression is returned, but the records aren't updated. > [!NOTE] > > 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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) # 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/indexes/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/indexes/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, 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/v7/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/indexes/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/indexes/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-07" \ -d '{ "namespace": "example-namespace", "filter": { "document_title": {"$eq": "Introduction to Vector Databases"} }, "setMetadata": { "author": "Del Klein" } }' ``` ### Handling large updates > [!TIP] > > 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/indexes/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-07" \ -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} { "matchedRecords": 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: 2026-07" \ -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} { "matchedRecords": 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/indexes/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-07" \ -d '{ "dry_run": true, "namespace": "example-namespace", "filter": { "document_title": {"$eq": "Introduction to Vector Databases"} }, "setMetadata": { "author": "Del Klein" } }' ``` ```json theme={null} { "matchedRecords": 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: 2026-07" \ -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/indexes/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-07" \ -d '{ "dry_run": true, "namespace": "example-namespace", "filter": { "document_title": {"$eq": "Introduction to Vector Databases"} }, "setMetadata": { "author": "Del Klein" } }' ``` ```json theme={null} { "matchedRecords": 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, per [Update limits](/reference/api/database-limits/operation-limits#update-limits). Use `"dry_run": true` to check if you need to run the request multiple times. See the example above for details. * Large update-by-metadata requests can be slow to process. A request that matches many records takes longer to complete and to be reflected, so size the work with `dry_run` and batch it. See [Handling large updates](#handling-large-updates). * You can add or change metadata across multiple records, but you can't remove metadata fields. ## Remove a metadata field To remove a metadata field from a record, use the [upsert](/guides/legacy/vectors-api/upsert-vectors) 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/data/check-data-freshness#check-the-log-sequence-number) to check whether an update request has completed. # Upsert vectors into a legacy vector index Source: https://docs.pinecone.io/guides/legacy/vectors-api/upsert-vectors Upsert dense and sparse vectors into a legacy vector index with the legacy Vectors API, in batches or in parallel. > [!NOTE] > > New projects should use the [Documents API](/guides/get-started/documents-api). To move an existing index, see [Move to the Documents API](/guides/indexes/move-to-the-documents-api). This page shows you how to upsert records into a namespace in a legacy vector index with the legacy Vectors API. For a document index, see [Upsert data](/guides/data/upsert-data). If a record ID already exists, upserting overwrites the entire record. To change only part of a record, [update](/guides/legacy/vectors-api/update-vectors) it. ## Upsert dense vectors To upsert dense vectors into an [index of dense vectors](/guides/legacy/vectors-api/create-a-vector-index#dense-vectors), use the [Upsert records](/reference/api/latest/data-plane/upsert) operation: * Specify the [`namespace`](/guides/indexes/index-data-overview#namespaces) to upsert into. If the namespace doesn't exist, it's 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/indexes/index-data-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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) 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/indexes/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/indexes/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, 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/v7/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/indexes/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/indexes/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-07" \ -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 To upsert sparse vectors into an [index of sparse vectors](/guides/legacy/vectors-api/create-a-vector-index#sparse-vectors), use the [Upsert records](/reference/api/latest/data-plane/upsert) operation: * Specify the [`namespace`](/guides/indexes/index-data-overview#namespaces) to upsert into. If the namespace doesn't exist, it's 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/indexes/index-data-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/indexes/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/indexes/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("INDEX_NAME"); // 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/v7/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/indexes/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 "https://$INDEX_HOST/vectors/upsert" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" \ -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 in batches > [!TIP] > > To control costs when ingesting large datasets (10,000,000+ records), use [import](/guides/data/import-data) instead of upsert. Send upserts in batches to help increase throughput. A batch should be as large as possible (up to 1,000 records) without exceeding the [max request size of 2 MB](#upsert-limits). The number of records that fit in one batch depends on the vector dimension and metadata size: | Dimension | Metadata (bytes) | Max batch size | | :- | :- | :- | | 386 | 0 | 1,000 | | 768 | 500 | 559 | | 1536 | 2000 | 245 | ```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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) 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 pc = new Pinecone({ apiKey: "YOUR_API_KEY" }); // To get the unique host for an index, // see https://docs.pinecone.io/guides/indexes/target-an-index const index = pc.index({ host: "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 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.ArrayList; import java.util.List; import java.util.Random; public class UpsertBatchExample { private static final int RECORD_COUNT = 10000; private static final int RECORD_DIMENSION = 128; private static final int BATCH_SIZE = 200; 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/indexes/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "INDEX_NAME"); List vectors = generateVectors(); // Upsert data with 200 vectors per upsert request for (int i = 0; i < vectors.size(); i += BATCH_SIZE) { index.upsert(vectors.subList(i, Math.min(i + BATCH_SIZE, vectors.size())), "example-namespace"); } } // Example data generation function, creates many (id, vector) pairs private static List generateVectors() { Random random = new Random(); List vectors = new ArrayList<>(); for (int i = 0; i < RECORD_COUNT; i++) { List values = new ArrayList<>(); for (int j = 0; j < RECORD_DIMENSION; j++) { values.add(random.nextFloat()); } vectors.add(new VectorWithUnsignedIndices("id-" + i, values)); } return vectors; } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "math/rand" "github.com/pinecone-io/go-pinecone/v7/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/indexes/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) } // Example data: 10,000 vectors with 128 dimensions vectors := make([]*pinecone.Vector, 10000) for i := range vectors { values := make([]float32, 128) for j := range values { values[j] = rand.Float32() } vectors[i] = &pinecone.Vector{Id: fmt.Sprintf("id-%d", i), Values: &values} } // Upsert 200 vectors per request batchSize := 200 for start := 0; start < len(vectors); start += batchSize { end := min(start+batchSize, len(vectors)) if _, err := idxConnection.UpsertVectors(ctx, vectors[start:end]); err != nil { log.Fatalf("Failed to upsert batch starting at %d: %v", start, err) } } } ``` ## Upsert in parallel > [!TIP] > > Python SDK v6.0.0 and later provide `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). Asyncio support lets you use Pinecone with async web frameworks such as FastAPI, Quart, and Sanic. For details, see [Async requests](/reference/sdks/python/overview#async-requests). Send multiple upserts in parallel to help increase throughput. Each upsert call blocks until the response arrives, so send several at once. Upserts can be made asynchronously: ```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/indexes/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 pc = new Pinecone({ apiKey: "YOUR_API_KEY" }); // To get the unique host for an index, // see https://docs.pinecone.io/guides/indexes/target-an-index const index = pc.index({ host: "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 io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.unsigned_indices_model.VectorWithUnsignedIndices; import java.util.ArrayList; import java.util.List; import java.util.Random; import java.util.concurrent.ExecutorService; import java.util.concurrent.Executors; import java.util.concurrent.TimeUnit; public class UpsertParallelExample { private static final int RECORD_COUNT = 10000; private static final int RECORD_DIMENSION = 128; private static final int BATCH_SIZE = 200; public static void main(String[] args) throws InterruptedException { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/indexes/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "INDEX_NAME"); List vectors = generateVectors(); // Send up to 10 requests of 200 vectors at a time ExecutorService executor = Executors.newFixedThreadPool(10); for (int i = 0; i < vectors.size(); i += BATCH_SIZE) { List batch = vectors.subList(i, Math.min(i + BATCH_SIZE, vectors.size())); executor.submit(() -> index.upsert(batch, "example-namespace")); } // Wait for all requests to finish executor.shutdown(); executor.awaitTermination(5, TimeUnit.MINUTES); } // Example data generation function, creates many (id, vector) pairs private static List generateVectors() { Random random = new Random(); List vectors = new ArrayList<>(); for (int i = 0; i < RECORD_COUNT; i++) { List values = new ArrayList<>(); for (int j = 0; j < RECORD_DIMENSION; j++) { values.add(random.nextFloat()); } vectors.add(new VectorWithUnsignedIndices("id-" + i, values)); } return vectors; } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "math/rand" "sync" "github.com/pinecone-io/go-pinecone/v7/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/indexes/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) } // Example data: 10,000 vectors with 128 dimensions vectors := make([]*pinecone.Vector, 10000) for i := range vectors { values := make([]float32, 128) for j := range values { values[j] = rand.Float32() } vectors[i] = &pinecone.Vector{Id: fmt.Sprintf("id-%d", i), Values: &values} } // Send up to 10 requests of 200 vectors at a time batchSize := 200 semaphore := make(chan struct{}, 10) errs := make(chan error, len(vectors)/batchSize+1) var wg sync.WaitGroup for start := 0; start < len(vectors); start += batchSize { batch := vectors[start:min(start+batchSize, len(vectors))] wg.Add(1) semaphore <- struct{}{} go func(start int, batch []*pinecone.Vector) { defer wg.Done() defer func() { <-semaphore }() if _, err := idxConnection.UpsertVectors(ctx, batch); err != nil { errs <- fmt.Errorf("batch starting at %d: %w", start, err) } }(start, batch) } wg.Wait() close(errs) for err := range errs { log.Printf("Failed to upsert %v", err) } } ``` ### Python SDK with gRPC The Python SDK with gRPC can upsert faster. Unlike REST, gRPC multiplexes requests, so it handles many requests in parallel without head-of-line blocking. You can also pass retry strategies to the gRPC SDK, including [exponential backoff](/guides/production/error-handling#implement-retry-logic). The gRPC client supports legacy vector indexes only. gRPC support is included in the base `pinecone` package, and upsert, query, fetch, and delete use the same syntax as the standard SDK. To use it, 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/indexes/target-an-index index = pc.index(host="INDEX_HOST", grpc=True) ``` To send multiple upserts in parallel, use `upsert_async`, which returns a future for each request: ```Python Python theme={null} def chunker(seq, batch_size): return (seq[pos:pos + batch_size] for pos in range(0, len(seq), batch_size)) futures = [ index.upsert_async(vectors=chunk) for chunk in chunker(data, batch_size=200) ] # Wait for and retrieve responses (this raises in case of error) [future.result() for future in futures] ``` > [!NOTE] > > Upserts through the gRPC SDK can hit write throttling sooner. If this happens often, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). ## Upsert limits | Metric | Limit | | :- | :- | | Max [batch size](/guides/legacy/vectors-api/upsert-vectors#upsert-in-batches) for records with vectors | 1,000 records, up to 2 MB total | | Max batch size for records with text | 96 records | | Max documents per upsert request | 1,000, or 96 when the schema declares `embed` or `sparse_embed` | | 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](/guides/search/full-text-search/text-processing#tokens-and-analyzers) | 1,024 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 limit for text is lower because Pinecone converts that text to vectors at upsert time with [integrated embedding](/guides/indexes/index-data-overview#integrated-embedding), and 96 is the max batch size of the [hosted embedding models](/guides/indexes/index-configuration#embedding-models) doing the conversion. The 40 KB filterable metadata limit doesn't apply to `full_text_search` text fields. # Diagnose poor search results Source: https://docs.pinecone.io/guides/optimize/debug-recall Find out whether poor search results come from your embedding model or from Pinecone recall by comparing exact brute-force search with your index's results. Poor search results have one of two causes: the embedding model doesn't place relevant records near your queries, or the index doesn't return the true nearest neighbors (low recall). Comparing exact brute-force search with your index's results tells you which one. **1. Build an evaluation set** Choose at least 10 queries and a source dataset that resembles your production data, for example 100,000 records. For each query, label the records in the source dataset that are correct answers. Then choose an evaluation metric that fits your use case. For guidance, see [Evaluation measures in information retrieval](https://www.pinecone.io/learn/offline-evaluation/). **2. Generate embeddings** Use your model to embed the queries and the source dataset. **3. Measure model quality with brute-force search** Run an exact nearest-neighbor search for each query vector over the source vectors, for example with FAISS or NumPy, using the same similarity metric your index will use, and record the returned record IDs. Score the results against your labeled answers. If the score is too low, the problem is the model, not Pinecone. **4. Query your index** [Create an index](/guides/indexes/create-an-index) whose dimension and metric match your model and the brute-force search. [Upsert](/guides/data/upsert-data) the source vectors, run the same queries with the same `top_k`, and record the returned record IDs. **5. Calculate recall** For each query, recall is the fraction of the brute-force record IDs that Pinecone also returned. Average across all queries to get overall recall. If your index uses dedicated read nodes, query-time parameters trade recall for latency. See [Tune queries](/guides/optimize/dedicated-read-nodes/tune-queries). **6. Report low recall** If recall is too low for your use case, [contact support](/admin/support/contact-support) with the dataset and queries that reproduce the issue. # 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/indexes/index-data-overview#namespaces) in a logical way, you speed up queries by ensuring only relevant records are scanned. The same applies to [fetching records](/guides/data/fetch-data), [listing record IDs](/guides/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/indexes/manage-indexes#describe-an-index) operation. The following example shows how to target an index by host directly: > [!NOTE] > > 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", grpc=True) ``` ```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(config, connection, "INDEX_NAME"); } } ``` ```go Go {21} theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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/indexes/index-configuration#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/optimize/increase-throughput#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 at higher `top_k` values, and larger responses can raise round-trip latency. If you don't need vector values in your response, leave `include_values` at its default of `false` in [Search with a vector](/reference/api/latest/data-plane/query) requests. The [Fetch records](/reference/api/latest/data-plane/fetch) operation always returns values, so use `query` when you're searching and only need IDs or metadata. > [!NOTE] > > 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. Dedicated read nodes indexes cache values locally and aren't 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. > [!NOTE] > > Indexes built on [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) aren't subject to read unit limits for query, fetch, list, and full-text search operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) 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. # Dedicated read nodes concepts Source: https://docs.pinecone.io/guides/optimize/dedicated-read-nodes/concepts Node types, shards, replicas, and index fullness are the building blocks of a Pinecone dedicated read nodes index. 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 aren't met by `b1` nodes, or if `t1` nodes are more cost-effective than `b1` nodes for your workload. > [!NOTE] > > 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](/guides/optimize/dedicated-read-nodes/manage#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](/guides/optimize/dedicated-read-nodes/size-and-test#calculate-the-size-of-your-index) and then [calculate the number of shards](/guides/optimize/dedicated-read-nodes/size-and-test#number-of-shards). > [!WARNING] > > It's your responsibility to allocate enough shards for your index size. If you run out of shard capacity, writes are blocked (reads continue). Track how close you are with [index fullness](#index-fullness). ## 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](/guides/optimize/dedicated-read-nodes/scale#add-or-remove-replicas). * 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](/guides/optimize/dedicated-read-nodes/size-and-test#test-your-workload) and then [calculate the number of replicas](/guides/optimize/dedicated-read-nodes/size-and-test#number-of-replicas). > [!NOTE] > > 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 an index's allocated capacity is in use. Dedicated read nodes cache all of your data in memory and on local SSD, so fullness tracks both dimensions: * `memoryFullness`: how full the memory cache is. * `storageFullness`: how full the local SSD is. * `indexFullness`: the greater of the two, on a scale of 0 to 1. Storage usually fills first, but memory can be the limiting factor with `b1` nodes holding many low-dimension vectors, or `t1` nodes holding high-dimension vectors and lots of metadata. When `indexFullness` reaches 1.0 (100%), writes are blocked while reads continue. To check these values on demand, see [Monitor index fullness](/guides/optimize/dedicated-read-nodes/manage#monitor-index-fullness). To track them over time, use the [`pinecone_db_index_fullness` metrics](/guides/production/monitor-performance#available-metrics) via the [Prometheus or Datadog integration](/guides/production/monitor-performance#monitor-with-datadog). To decide when to add capacity, see [Add or remove shards](/guides/optimize/dedicated-read-nodes/scale#add-or-remove-shards). # Create a dedicated read nodes index Source: https://docs.pinecone.io/guides/optimize/dedicated-read-nodes/create Create a Pinecone dedicated read nodes index from scratch or from a backup of an existing index. ## From scratch **1. Create the index** Call [Create an index](/reference/api/2026-07/control-plane/create_index). In the request body, in the `read_capacity` object, set the following fields: | Field | Value | Notes | | :- | :- | :- | | `mode` | `Dedicated` | | | `dedicated.node_type` | `b1` or `t1` | See [node types](/guides/optimize/dedicated-read-nodes/concepts#node-types) | | `dedicated.scaling` | `Manual` | The only supported value | | `dedicated.manual.shards` | Number of [shards](/guides/optimize/dedicated-read-nodes/size-and-test#number-of-shards) needed | Minimum 1 shard; each shard provides 250 GB of storage | | `dedicated.manual.replicas` | Number of [replicas](/guides/optimize/dedicated-read-nodes/size-and-test#number-of-replicas) needed | Minimum 0 (this [pauses](/guides/optimize/dedicated-read-nodes/manage#pause-an-index) the index) | > [!NOTE] > > To learn how to determine the number of shards and replicas your index requires, see [Calculate the size of your index](/guides/optimize/dedicated-read-nodes/size-and-test#calculate-the-size-of-your-index). This example creates an index with two shards and one replica: ```bash Request expandable 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: 2026-07" \ -d '{ "name": "example-dedicated-index", "deletion_protection": "enabled", "tags": { "environment": "production" }, "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "_values": { "type": "dense_vector", "dimension": 1024, "metric": "cosine" } } }, "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 2, "replicas": 1 } } } }' ``` ```jsonc Response expandable theme={null} { "name": "example-dedicated-index", "status": { "ready": false, "state": "Initializing" }, "host": "example-dedicated-index-1c6ab6aa.svc.aped-4627-b74a.pinecone.io", "deployment": { "deployment_type": "managed", "region": "us-east-1", "cloud": "aws", "environment": "aped-4627-b74a" }, "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 } }, "schema": { "fields": { "_values": { "type": "dense_vector", "dimension": 1024, "metric": "cosine" } } }, "deletion_protection": "enabled", "tags": { "environment": "production" } } ``` The response includes two status fields: | Field | Description | | :- | :- | | **`status.state`** | Overall index status (for example, `Initializing`, `Ready`, `Terminating`) | | **`read_capacity.status.state`** | Read capacity status (`Migrating`, `Scaling`, `Ready`, `Error`) | > [!NOTE] > > When creating a dedicated read nodes index, `status.state` transitions to `Ready` as soon as the index is ready for reads and writes. > > However, `read_capacity.status.state` remains `Migrating` until the index scales to its full read capacity, at which point it transitions to `Ready`. **2. Add your data** After the index is created, [upsert](/guides/data/upsert-data) or [import](/guides/data/import-data) your data. > [!TIP] > > To upsert and search with text instead of vectors, create the index with a [hosted embedding model](/guides/indexes/index-configuration#embedding-models) instead. Call [Create an index with integrated embedding](/reference/api/2026-07/control-plane/create_for_model) and include the `read_capacity` object to configure dedicated read nodes. ## From a backup **1. Restore the backup** [Restore the backup](/guides/indexes/restore-an-index) to a new on-demand index with the same data as the original. **2. Delete extra namespaces** 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 support only [one namespace](/guides/optimize/dedicated-read-nodes/overview#namespace-limits). **3. Migrate to dedicated read nodes** Convert the restored on-demand index by following [Migrate to dedicated read nodes](/guides/optimize/dedicated-read-nodes/migrate). # Manage a dedicated read nodes index Source: https://docs.pinecone.io/guides/optimize/dedicated-read-nodes/manage Use a hosted embedding model, monitor fullness, change node types, pause, or convert a Pinecone dedicated read nodes index back to on-demand. ## Use a hosted embedding model To upsert and search with text instead of vectors, an index must use a [hosted embedding model](/guides/indexes/index-configuration#embedding-models). Set the model when you create the index, because you can't add one to an existing index. [Converting](/guides/indexes/convert-an-index) a legacy integrated index into a document index keeps its model, but converting a legacy vector index doesn't add one. To create a dedicated read nodes index with a hosted embedding model, call [Create an index with integrated embedding](/reference/api/2026-07/control-plane/create_for_model) and include the `read_capacity` object to set the node type, shards, and replicas. ## Monitor index fullness To check [index fullness](/guides/optimize/dedicated-read-nodes/concepts#index-fullness), call [Get index stats](/reference/api/2026-07/data-plane/describeindexstats). ### Example ```bash Request theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/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: 2026-07" ``` ```json Response 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`. Pinecone also [emits these values](/guides/production/monitor-performance#available-metrics). Use them to track fullness over time in Prometheus or Datadog, and to alert before your index reaches capacity. ## Change node types You can change node types in either direction (`b1` → `t1` or `t1` → `b1`). This operation doesn't require downtime, but can take up to 30 minutes to complete. > [!NOTE] > > The most predictable way to increase throughput is by increasing [replicas](/guides/optimize/dedicated-read-nodes/concepts#replicas). > [!WARNING] > > `t1` nodes [cache more data in memory](/guides/optimize/dedicated-read-nodes/concepts#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/2026-07/control-plane/configure_index). In the request body, set the following fields: | Field | Value | Notes | | :- | :- | :- | | `read_capacity.mode` | `Dedicated` | | | `read_capacity.dedicated.node_type` | `b1` or `t1` | See [node types](/guides/optimize/dedicated-read-nodes/concepts#node-types) | ### Example This example changes the node type from `b1` to `t1`: ```bash Request 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: 2026-07" \ -d '{ "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "t1" } } }' ``` ```json Response expandable theme={null} { "name": "example-dedicated-index", "status": { "ready": true, "state": "Ready" }, "host": "example-dedicated-index-1c6ab6aa.svc.aped-4627-b74a.pinecone.io", "deployment": { "deployment_type": "managed", "region": "us-east-1", "cloud": "aws", "environment": "aped-4627-b74a" }, "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "t1", "scaling": "Manual", "manual": { "shards": 1, "replicas": 1 } }, "status": { "state": "Scaling", "current_shards": 1, "current_replicas": 1 } }, "schema": { "fields": { "_values": { "type": "dense_vector", "dimension": 1024, "metric": "cosine" } } }, "deletion_protection": "disabled", "tags": null } ``` > [!NOTE] > > 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. ## Pause an index To pause an index, [set the number of replicas](/guides/optimize/dedicated-read-nodes/scale#add-or-remove-replicas) to 0. This operation can take up to 30 minutes to complete. > [!NOTE] > > While an index is paused, you can't write to it or read from it. For a paused index, you're billed for storage, but not for node costs, reads, or writes. ## Check the status of a configuration change 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/2026-07/control-plane/describe_index). ### Example ```bash Request 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: 2026-07" ``` ```jsonc Response expandable theme={null} { "name": "example-dedicated-index", "status": { "ready": true, "state": "Ready" }, "host": "example-dedicated-index-1c6ab6aa.svc.aped-4627-b74a.pinecone.io", "deployment": { "deployment_type": "managed", "region": "us-east-1", "cloud": "aws", "environment": "aped-4627-b74a" }, "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 } }, "schema": { "fields": { "_values": { "type": "dense_vector", "dimension": 1536, "metric": "cosine" } } }, "deletion_protection": "enabled", "tags": { "tag0": "value0" } } ``` The response includes two status fields: | Field | Description | | :- | :- | | **`status.state`** | Overall index status (for example, `Initializing`, `Ready`, `Terminating`) | | **`read_capacity.status.state`** | Read capacity status (`Migrating`, `Scaling`, `Ready`, `Error`) | When changing node types, shards, or replicas, monitor the read capacity status (`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 (Dedicated or OnDemand) 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. | > [!NOTE] > > 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. ## Convert to on-demand To convert a dedicated read nodes index back to on-demand, call [Configure an index](/reference/api/2026-07/control-plane/configure_index) and set `read_capacity.mode` to `OnDemand`. This converts the index in place, keeping the same index name and host. ```bash Request 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: 2026-07" \ -d '{ "read_capacity": { "mode": "OnDemand" } }' ``` ```jsonc Response expandable theme={null} { "name": "example-index", "status": { "ready": true, "state": "Ready" }, "host": "example-index-1c6ab6aa.svc.aped-4627-b74a.pinecone.io", "deployment": { "deployment_type": "managed", "region": "us-east-1", "cloud": "aws", "environment": "aped-4627-b74a" }, "read_capacity": { "mode": "OnDemand", "status": { "state": "Ready", "current_shards": null, "current_replicas": null } }, "schema": { "fields": { "_values": { "type": "dense_vector", "dimension": 1024, "metric": "cosine" } } }, "deletion_protection": "disabled", "tags": null } ``` If you'd rather return to on-demand on a fresh index, use the backup and restore path instead: 1. [Create a backup](/guides/indexes/back-up-an-index) of your dedicated read nodes index. 2. [Create a new index from the backup](/guides/indexes/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). # Migrate to dedicated read nodes Source: https://docs.pinecone.io/guides/optimize/dedicated-read-nodes/migrate Migrate an existing on-demand or pod-based Pinecone index to dedicated read nodes. ## From a pod-based index You can't migrate a pod-based index directly to dedicated read nodes. First complete [Migrate a pod-based index to serverless](/guides/legacy/pod-based-indexes/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 support only a [single namespace](/guides/optimize/dedicated-read-nodes/overview#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: **1. Create a backup of your index** Before migrating, [back up your index](/guides/indexes/back-up-an-index) so you can return to on-demand later, either by [converting back](/guides/optimize/dedicated-read-nodes/manage#convert-to-on-demand) or by restoring the backup to a new on-demand index. **2. Delete extra namespaces** 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 support only a [single namespace](/guides/optimize/dedicated-read-nodes/overview#namespace-limits). > [!WARNING] > > If this is a production index, be sure to make a [backup](/guides/indexes/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. **3. Calculate your index size** Determine how many [shards](/guides/optimize/dedicated-read-nodes/size-and-test#number-of-shards) you need by [sizing your index](/guides/optimize/dedicated-read-nodes/size-and-test#index-size). **4. Migrate the index** Call [Configure an index](/reference/api/2026-07/control-plane/configure_index). In the request body, in the `read_capacity` object, set the following fields: | Field | Value | Notes | | :- | :- | :- | | `mode` | `Dedicated` | | | `dedicated.node_type` | `b1` or `t1` | See [node types](/guides/optimize/dedicated-read-nodes/concepts#node-types) | | `dedicated.scaling` | `Manual` | The only supported value | | `dedicated.manual.shards` | Number of [shards](/guides/optimize/dedicated-read-nodes/size-and-test#number-of-shards) needed | Minimum 1 shard; each shard provides 250 GB of storage | | `dedicated.manual.replicas` | Number of [replicas](/guides/optimize/dedicated-read-nodes/size-and-test#number-of-replicas) needed | Minimum 0 (this [pauses](/guides/optimize/dedicated-read-nodes/manage#pause-an-index) the index) | This example migrates an index to dedicated read nodes using `b1` nodes, one shard, and one replica: ```bash Request 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: 2026-07" \ -d '{ "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 1, "replicas": 1 } } } }' ``` ```jsonc Response expandable theme={null} { "name": "example-index-to-migrate", "status": { "ready": true, "state": "Ready" }, "host": "example-index-to-migrate-1c6ab6aa.svc.aped-4627-b74a.pinecone.io", "deployment": { "deployment_type": "managed", "region": "us-east-1", "cloud": "aws", "environment": "aped-4627-b74a" }, "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 } }, "schema": { "fields": { "_values": { "type": "dense_vector", "dimension": 1024, "metric": "cosine" } } }, "deletion_protection": "disabled", "tags": null } ``` The response includes two status fields: | Field | Description | | :- | :- | | **`status.state`** | Overall index status (for example, `Initializing`, `Ready`, `Terminating`) | | **`read_capacity.status.state`** | Read capacity status (`Migrating`, `Scaling`, `Ready`, `Error`) | > [!WARNING] > > 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. **5. Monitor the migration** [Check the status](/guides/optimize/dedicated-read-nodes/manage#check-the-status-of-a-configuration-change) until `read_capacity.status.state` is `Ready`. **6. Verify performance** Confirm the index meets your latency and throughput targets. # Dedicated read nodes overview Source: https://docs.pinecone.io/guides/optimize/dedicated-read-nodes/overview Dedicated read nodes give a Pinecone index its own provisioned read hardware for predictable, low-latency performance at high query volumes. 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](/guides/optimize/dedicated-read-nodes/concepts#node-types), number of [shards](/guides/optimize/dedicated-read-nodes/concepts#shards), and number of [replicas](/guides/optimize/dedicated-read-nodes/concepts#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. ![](https://mintcdn.com/pinecone/id0yJFEuv83Kq3F9/images/drn-read-path_light.png?fit=max\&auto=format\&n=id0yJFEuv83Kq3F9\&q=85\&s=d139d1364ec4349c0028f6036769a61a) Read path for dedicated read nodes ## On-demand vs. dedicated read nodes 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/cost/understand-cost#read-units) (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/cost/understand-cost#storage), [write](/guides/cost/understand-cost#write-units), and [egress](/guides/cost/understand-cost#egress) costs based on usage | [Storage](/guides/cost/understand-cost#storage), [write](/guides/cost/understand-cost#write-units), and [egress](/guides/cost/understand-cost#egress) 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 RU/second per index and per namespace (adjustable)](/reference/api/database-limits/rate-limits) | No read rate limits (only bounded by CPU capacity) | | Scaling | Automatic; Pinecone handles capacity | Manual; add [shards](/guides/optimize/dedicated-read-nodes/concepts#shards) for storage, add [replicas](/guides/optimize/dedicated-read-nodes/concepts#replicas) for throughput | | Query-time tuning | Parameters accepted but have no effect | Optional [`scan_factor` and `max_candidates`](/guides/optimize/dedicated-read-nodes/tune-queries) 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 | In [BYOC](/guides/production/bring-your-own-cloud), on-demand indexes share one pool of nodes in your own cloud account instead of multi-tenant Pinecone infrastructure, and both modes are billed per node rather than per read unit. See [BYOC pricing](/guides/production/bring-your-own-cloud#pricing). ## 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: > [accordion] Predictable, consistent performance and cost > > 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. > [accordion] High throughput without rate limits or throttling > > On-demand indexes are subject to [read unit rate limits](/reference/api/database-limits/rate-limits) (default: 2,000 RU/second per index and per namespace). > > A high query volume on a large namespace can exceed these limits. For example, a 15 GB namespace at 150 QPS requires approximately 2,250 RU/second (`15 RU per query × 150 QPS`), which exceeds both default limits. > > 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. > [accordion] Recommendation engines and real-time use cases > > 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. > [accordion] Single namespace workload > > Dedicated read nodes indexes support only a single namespace. If your application requires multiple namespaces, on-demand is a better fit. > > > [!NOTE] > > > > To request early access to multi-namespace support, [contact support](https://app.pinecone.io/organizations/-/settings/support/ticket). > [accordion] When *not* to use dedicated read nodes > > 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 support single-namespace indexes only, so multi-tenant applications requiring namespace-based isolation should use on-demand. > > For these scenarios, on-demand's elasticity and usage-based pricing provide better cost efficiency than provisioning dedicated capacity. > > > [!NOTE] > > > > 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. > [accordion] Cost considerations > > 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, storage, and egress 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. > [accordion] Test results for your workload > > 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](/guides/optimize/dedicated-read-nodes/size-and-test#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/). ## Limits The following limits apply to dedicated read nodes: ### Read limits Dedicated read nodes indexes aren't 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](/guides/optimize/dedicated-read-nodes/scale#add-or-remove-replicas) to increase compute resources, or use [query-time search parameters](/guides/optimize/dedicated-read-nodes/tune-queries) to reduce per-query compute and increase throughput without adding replicas. ### Write limits 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](/guides/optimize/dedicated-read-nodes/scale#add-or-remove-shards) to increase available storage. To determine how close to the write limit you are, [check index fullness](/guides/optimize/dedicated-read-nodes/manage#monitor-index-fullness). ### Namespace limits Dedicated read nodes indexes support a single namespace. To request early access to multi-namespace support, [contact support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Shard, replica, and node limits | Resource | Limit | | :- | :- | | [Shards](/guides/optimize/dedicated-read-nodes/concepts#shards) | Minimum 1 per index | | [Replicas](/guides/optimize/dedicated-read-nodes/concepts#replicas) | Minimum 0 per index, where 0 [pauses the index](/guides/optimize/dedicated-read-nodes/manage#pause-an-index) | | [Nodes](/guides/optimize/dedicated-read-nodes/concepts#node-types) | Maximum 20 per project | Nodes are a project-level limit, not a per-index limit. To calculate your total node count, multiply `shards × replicas` for each of your project's indexes, then sum the results; this total must not exceed 20. For example, two indexes that each have two shards and three replicas total `(2 × 3) + (2 × 3) = 12` nodes. To increase your project's node limit, [contact support](https://app.pinecone.io/organizations/-/settings/support/ticket). > [!NOTE] > > 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. ### Memory fullness `memoryFullness` is an approximation and doesn't yet account for metadata. For more information, see [Index fullness](/guides/optimize/dedicated-read-nodes/concepts#index-fullness). ## Cost > [!NOTE] > > For the latest pricing information, see the [Pinecone pricing page](https://www.pinecone.io/pricing/). The cost of an index has four components: read costs, write costs, storage costs, and egress costs. On-demand and dedicated read nodes share infrastructure for writes and storage, so these costs are the same. Egress is billed the same way on both, because it depends on the data returned to you rather than on the hardware serving the read. 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/cost/understand-cost#read-units): 1 RU per 1 GB namespace size per query | Fixed hourly rate: Based on [node type](/guides/optimize/dedicated-read-nodes/concepts#node-types), [shards](/guides/optimize/dedicated-read-nodes/concepts#shards), and [replicas](/guides/optimize/dedicated-read-nodes/concepts#replicas) | | Write costs | [Usage-based](/guides/cost/understand-cost#write-units) | [Usage-based](/guides/cost/understand-cost#write-units) (same as on-demand) | | Storage costs | [Usage-based](/guides/cost/understand-cost#storage) | [Usage-based](/guides/cost/understand-cost#storage) (same as on-demand) | | Egress costs | [Usage-based](/guides/cost/understand-cost#egress) beyond your plan's [egress allowance](/guides/cost/understand-cost#egress-allowance) | [Usage-based](/guides/cost/understand-cost#egress) (same as on-demand) | > [!NOTE] > > If you use a hosted model for search or reranking, there are additional [inference costs](https://www.pinecone.io/pricing). ### Calculate dedicated read nodes costs To calculate the total cost of a dedicated read nodes index, use this formula: ``` (Node rate × shards × replicas) + storage costs + write costs + egress costs ``` | Term | Description | | :- | :- | | Node rate | Monthly rate for the [node type](/guides/optimize/dedicated-read-nodes/concepts#node-types) (`b1` or `t1`), which varies by cloud region. See [Pinecone pricing](https://www.pinecone.io/pricing/). | | Shards | Number of [shards](/guides/optimize/dedicated-read-nodes/concepts#shards) allocated | | Replicas | Number of [replicas](/guides/optimize/dedicated-read-nodes/concepts#replicas) allocated | | Storage costs | [Usage-based](/guides/cost/understand-cost#storage), same as on-demand | | Write costs | [Usage-based](/guides/cost/understand-cost#write-units), same as on-demand | | Egress costs | [Usage-based](/guides/cost/understand-cost#egress) beyond your plan's [egress allowance](/guides/cost/understand-cost#egress-allowance), same as on-demand | > [!TIP] > > 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, write, and egress costs ``` # Scale a dedicated read nodes index Source: https://docs.pinecone.io/guides/optimize/dedicated-read-nodes/scale Scale a Pinecone dedicated read nodes index by adding replicas for query throughput and shards for storage capacity. ## When to scale Dedicated read nodes don't yet scale automatically. You decide when to scale, guided by two signals: | Scenario | What to check | What to do | | :- | :- | :- | | Query load | CPU usage | [Add replicas](#add-or-remove-replicas) | | Data volume | Index fullness | [Add shards](#add-or-remove-shards) | Diagnose which one you're facing before you scale. Adding shards won't relieve query latency that's driven by CPU saturation, and adding replicas won't create room on a shard that's running out of space. ## Add or remove replicas CPU usage reflects query pressure. As query load outgrows what your replicas can serve, query latency climbs and throughput drops. Pinecone exposes CPU usage as the `pinecone_db_drn_cpu_usage_percent` metric, reported per shard. To collect it, [monitor your index with Prometheus](/guides/production/monitor-performance#monitor-with-prometheus). Alert on the highest value across your shards rather than the index-wide average, which can look healthy while a single shard is already saturated: ```shell theme={null} max(avg_over_time(pinecone_db_drn_cpu_usage_percent{index_name="docs-example"}[5m])) ``` Add a replica when this exceeds 80%. Averaging over a window keeps a brief spike from triggering a scale-up, so shorten or lengthen the window to suit how quickly your traffic shifts. Throughput scales approximately linearly with replicas. For high availability, allocate `n+1` replicas, where `n` is the minimum number of replicas required to serve your expected throughput at your target latency. See [Number of replicas](/guides/optimize/dedicated-read-nodes/size-and-test#number-of-replicas). > [!TIP] > > If you'd rather reduce per-query compute than add replicas, you can also tune [query-time search parameters](/guides/optimize/dedicated-read-nodes/tune-queries) to trade some recall for higher throughput. To add or remove [replicas](/guides/optimize/dedicated-read-nodes/concepts#replicas), call [Configure an index](/reference/api/2026-07/control-plane/configure_index). This operation doesn't require downtime, but can take up to 30 minutes to complete. In the request body, set the following fields: | Field | Value | Notes | | :- | :- | :- | | `read_capacity.mode` | `Dedicated` | | | `read_capacity.dedicated.scaling` | `Manual` | | | `read_capacity.dedicated.manual.replicas` | Desired number of [replicas](/guides/optimize/dedicated-read-nodes/concepts#replicas) | Add replicas to increase query throughput | ### Example ```bash Request 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: 2026-07" \ -d '{ "read_capacity": { "mode": "Dedicated", "dedicated": { "scaling": "Manual", "manual": { "replicas": 2 } } } }' ``` ```jsonc Response expandable theme={null} { "name": "example-dedicated-index", "status": { "ready": true, "state": "Ready" }, "host": "example-dedicated-index-1c6ab6aa.svc.aped-4627-b74a.pinecone.io", "deployment": { "deployment_type": "managed", "region": "us-east-1", "cloud": "aws", "environment": "aped-4627-b74a" }, "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 } }, "schema": { "fields": { "_values": { "type": "dense_vector", "dimension": 1024, "metric": "cosine" } } }, "deletion_protection": "disabled", "tags": null } ``` > [!NOTE] > > 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. ## Add or remove shards [Index fullness](/guides/optimize/dedicated-read-nodes/concepts#index-fullness) reflects data volume. Writes are blocked once the index reaches capacity, while reads continue normally. > [!NOTE] > > [Add shards](/guides/optimize/dedicated-read-nodes/scale#add-or-remove-shards) when [index fullness](/guides/optimize/dedicated-read-nodes/concepts#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. To check the current value, see [Monitor index fullness](/guides/optimize/dedicated-read-nodes/manage#monitor-index-fullness). To add or remove [shards](/guides/optimize/dedicated-read-nodes/concepts#shards), call [Configure an index](/reference/api/2026-07/control-plane/configure_index). This operation doesn't require downtime, but can take up to 30 minutes to complete. In the request body, set the following fields: | Field | Value | Notes | | :- | :- | :- | | `read_capacity.mode` | `Dedicated` | | | `read_capacity.dedicated.scaling` | `Manual` | | | `read_capacity.dedicated.manual.shards` | Desired number of [shards](/guides/optimize/dedicated-read-nodes/concepts#shards) | Each shard provides 250 GB of storage | ### Example ```bash Request 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: 2026-07" \ -d '{ "read_capacity": { "mode": "Dedicated", "dedicated": { "scaling": "Manual", "manual": { "shards": 3 } } } }' ``` ```jsonc Response expandable theme={null} { "name": "example-dedicated-index", "status": { "ready": true, "state": "Ready" }, "host": "example-dedicated-index-1c6ab6aa.svc.aped-4627-b74a.pinecone.io", "deployment": { "deployment_type": "managed", "region": "us-east-1", "cloud": "aws", "environment": "aped-4627-b74a" }, "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 } }, "schema": { "fields": { "_values": { "type": "dense_vector", "dimension": 1024, "metric": "cosine" } } }, "deletion_protection": "disabled", "tags": null } ``` > [!NOTE] > > 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. # Size and test a dedicated read nodes index Source: https://docs.pinecone.io/guides/optimize/dedicated-read-nodes/size-and-test Calculate how many shards and replicas a Pinecone dedicated read nodes index needs, and load-test your workload to validate the configuration. ## Calculate the size of your index To determine how many [shards](/guides/optimize/dedicated-read-nodes/concepts#shards) your index requires, calculate your index size and then apply the [number of shards](#number-of-shards) formula. ### Index size A document in a document index can include any combination of `string` fields with `full_text_search` enabled, a dense vector, and a sparse vector. A record in a legacy vector index can include a dense vector, a sparse vector, or both. Use the formula that matches your index to calculate total size: > [tab] Document index > > A [document index](/guides/indexes/index-data-overview#document-index) contains documents. Each document's size is its ID, its metadata, and the data in every schema field it holds. > > ```text Calculate size theme={null} > Index size = Number of documents × ( > ID size + > Metadata size + > Total full-text-search field 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 documents. Metadata is every field that isn't declared in the schema. > * `Total full-text-search field size`: The combined UTF-8 byte length of the text in all `string` fields with `full_text_search` enabled, averaged across all documents. A `string` field with [integrated embedding](/guides/indexes/index-data-overview#integrated-embedding) stores its text, which counts here, unless it sets `store_text: false`, in which case only its generated vector counts. If a field has both, count its text here and its generated vector below. > * Each `Dense vector dimension` uses 4 bytes. Sum the dimensions of every dense vector in the document, whether you upsert it or Pinecone generates it for an integrated-embedding field. Omit this term if the schema has no dense vector. > * `Number of non-zero sparse values`: Average number across all documents, including those without sparse vectors. Count every sparse vector in the document, whether you upsert it or Pinecone generates it. Each non-zero value uses 8 bytes. Omit this term if the schema has no sparse vector. > > These examples assume 8-byte IDs: > > | Documents | Avg total full-text-search field size | Dense vector dimensions | Avg number of non-zero sparse values | Avg metadata size | Index size | > | :- | :- | :- | :- | :- | :- | > | 500,000 | 2,000 bytes | None | None | 500 bytes | 1.25 GB | > | 1,000,000 | 5,000 bytes | 1024 | None | 1,000 bytes | 10.1 GB | > | 5,000,000 | 2,000 bytes | 768 | 100 | 500 bytes | 31.9 GB | > > > [!NOTE] > > > > Example: 1,000,000 documents × (8-byte ID + 5,000 bytes of full-text-search text + (1024 dense vector dimensions × 4 bytes) + 1,000 bytes of metadata) = 10.1 GB > [tab] Index of dense vectors > > An [index of dense vectors](/guides/indexes/index-data-overview#indexes-with-dense-vectors) contains records with one dense vector each. > > > [!NOTE] > > > > Records can also contain sparse vectors (when the index metric is set to `dotproduct`), which can be useful for [hybrid search](/guides/legacy/vectors-api/hybrid-search-single-index). To learn how to calculate size in that case, see [Index with both dense and sparse vectors](#index-with-both-dense-and-sparse-vectors). > > ```text Calculate size (assuming no sparse vectors) theme={null} > 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. > > 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 | > > > [!NOTE] > > > > Example: 500,000 records × (8-byte ID + (768 dense vector dimensions × 4 bytes) + 500 bytes of metadata) = 1.79 GB > [tab] Index of sparse vectors > > An [index of sparse vectors](/guides/indexes/index-data-overview#indexes-with-sparse-vectors) contains records with one sparse vector each. > > ```text Calculate size theme={null} > 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. > > 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 | > > > [!NOTE] > > > > Example: 500,000 records × (8-byte ID + (10 non-zero sparse values × 8 bytes) + 500 bytes of metadata) = 0.29 GB > [tab] Index with both dense and sparse vectors > > An [index with both dense and sparse vectors](/guides/legacy/vectors-api/hybrid-search-single-index) contains records that each have one dense vector and an optional sparse vector. > > ```text Calculate size theme={null} > 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. > > 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 | > > > [!NOTE] > > > > 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](/guides/optimize/dedicated-read-nodes/manage#pause-an-index) by reducing its replicas to 0. * After you've created your index, [monitor its fullness](/guides/optimize/dedicated-read-nodes/manage#monitor-index-fullness). > [!NOTE] > > [Add shards](/guides/optimize/dedicated-read-nodes/scale#add-or-remove-shards) when [index fullness](/guides/optimize/dedicated-read-nodes/concepts#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. For how throughput scales with replicas and how to size for high availability, see [Replicas](/guides/optimize/dedicated-read-nodes/concepts#replicas). ## 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. **1. Calculate the size of your index** Determine how many shards your index requires. See [Calculate the size of your index](#calculate-the-size-of-your-index). **2. Create and populate a test index** Populate a [dedicated read nodes index](/guides/optimize/dedicated-read-nodes/create) with data representative of your workload. > [!TIP] > > If you don't restore your test index from a backup, you can [upsert](/guides/data/upsert-data) or [import](/guides/data/import-data) your data. **3. Migrate your test index to dedicated read nodes (if necessary)** If your test index is on-demand, [migrate it](/guides/optimize/dedicated-read-nodes/migrate) with a single `b1` replica to start. > [!WARNING] > > Don't migrate your production index yet. At this point, you're just testing your workload. **4. Run a load test** Send realistic query patterns against your test index, gradually increasing QPS. For example, start at 10 QPS for about 30 minutes, then step up in 10-QPS increments while monitoring latency. Note the QPS where latency crosses your target threshold. **5. Calculate replicas** From the QPS a single replica sustained, [determine how many replicas](#number-of-replicas) you need for your target throughput. **6. Adjust and re-test** If you haven't hit your performance and cost goals, change the configuration and test again: * [Add or remove shards](/guides/optimize/dedicated-read-nodes/scale#add-or-remove-shards) for storage capacity * [Add or remove replicas](/guides/optimize/dedicated-read-nodes/scale#add-or-remove-replicas) for throughput * [Change node types](/guides/optimize/dedicated-read-nodes/manage#change-node-types) for different performance characteristics Continue iterating until you meet your requirements with room for growth. # Tune queries on dedicated read nodes Source: https://docs.pinecone.io/guides/optimize/dedicated-read-nodes/tune-queries Tune scan_factor and max_candidates on a Pinecone dedicated read nodes index to trade recall for lower latency and higher throughput. 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-demand indexes accept the parameters but ignore them. 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, so 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` isn't 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 isn't 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](/guides/optimize/dedicated-read-nodes/size-and-test#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 * **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, so existing queries aren't affected. * **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 "https://$INDEX_HOST/query" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -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` | > [!NOTE] > > `scan_factor` and `max_candidates` don't 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. # 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/key-terms#record) in an index must contain an ID and a dense or sparse vector, depending on the [type of index](/guides/indexes/index-data-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. To combine them, 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/indexes/index-data-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 doesn't 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 aren't 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 the [Configure an index](/reference/api/latest/control-plane/configure_index) operation. 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 embedding you can't choose `query` or `passage` per request. If you need that control, embed text yourself with [standalone embedding](/reference/api/latest/inference/generate-vectors) and search with the [Search with a vector](/reference/api/latest/data-plane/query) operation using your own vectors. For pure exact-match retrieval, a [sparse index](/guides/indexes/index-data-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 keyword 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 search](/guides/search/sparse-vector-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/legacy/vectors-api/hybrid-search-single-index). 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/legacy/vectors-api/hybrid-search-single-index#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/legacy/vectors-api/hybrid-search-separate-indexes). 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/key-terms#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 full-text 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, batch upserts, parallel upserts and searches, and Python SDK options like async requests and gRPC. ## Import from object storage [Importing from object storage](/guides/data/import-data) is the most efficient and cost-effective way to load large numbers of documents or records into an index. You store your data in object storage as [JSON Lines](https://jsonlines.org/) (JSONL) files for a document index or Parquet files for a vector index. Then you integrate your object storage with Pinecone and start an asynchronous, long-running operation that imports and indexes your data. You can't import into an index whose schema declares `embed` or `sparse_embed`, so upsert in batches instead. ## Upsert in batches [Upserting in batches](/guides/data/upsert-data#upsert-in-batches) is another efficient way to ingest large numbers of documents or records. A batch can hold up to 1,000 documents or records, or 96 when Pinecone embeds the text. See [Upsert limits](/reference/api/database-limits/operation-limits#upsert-limits). Batch upserting is also a good option if you can't work around bulk import's [limitations](/guides/data/import-data#import-limits). For a document index, the Python SDK's `index.documents.batch_upsert` method splits a list of documents into batches and sends them in parallel. Failed batches are returned in the result instead of raised, so you can retry only the failures. For example, the following code upserts 1,000 documents into an index whose `chunk_text` field declares `embed`, then resends any batches a retry could help: ```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/indexes/target-an-index index = pc.index(host="INDEX_HOST") documents = [{"_id": f"doc{i}", "chunk_text": f"Paragraph {i}"} for i in range(1000)] result = index.documents.batch_upsert(namespace="example-namespace", documents=documents) retryable = [item for error in result.errors if error.retryable for item in error.items] if retryable: index.documents.batch_upsert(namespace="example-namespace", documents=retryable) ``` ## Upsert and search in parallel Pinecone is thread-safe, so you can send multiple [upsert](/guides/data/upsert-data#upsert-in-parallel) requests and multiple [search](#parallel-queries) requests in parallel to help increase throughput. ### Parallel queries 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 async web frameworks such as FastAPI, Quart, and Sanic, and can make running queries in parallel much more efficient. For details, see [Async requests](/reference/sdks/python/overview#async-requests). You can also run synchronous queries in parallel with a thread pool. For example, the following code runs three text searches concurrently against a document index whose `chunk_text` field declares `embed`: ```python Python theme={null} from concurrent.futures import ThreadPoolExecutor 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/indexes/target-an-index index = pc.index(host="INDEX_HOST") queries = ["Disease prevention", "Healthy digestion", "Immune support"] def run_query(query): return index.documents.search( namespace="example-namespace", top_k=3, score_by=[{"type": "embed", "fields": ["chunk_text"], "query": query}], include_fields=["chunk_text"], ) with ThreadPoolExecutor(max_workers=4) as executor: results = list(executor.map(run_query, queries)) for query, result in zip(queries, results): print(query, [match._id for match in result.matches]) ``` On a legacy vector index, run `index.query` with query vectors instead, using the same client and thread pool: ```python Python theme={null} def run_query(vector): return index.query(namespace="example-namespace", vector=vector, top_k=3) # Replace with your query embeddings, which must match the index's dimension (1536 in this example) query_vectors = [ [0.1, 0.2] * 768, [0.2, 0.1] * 768, ] with ThreadPoolExecutor(max_workers=4) as executor: results = list(executor.map(run_query, query_vectors)) ``` ## Python SDK options ### Use gRPC For a legacy vector index, use the [Python SDK with gRPC](/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. The gRPC client doesn't support the Documents API, so use the sync or async client for a document index. ### Upsert from a dataframe To quickly ingest data into a legacy vector index with 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 performs especially well with Parquet datasets. # Test Pinecone at scale Source: https://docs.pinecone.io/guides/optimize/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. > [!NOTE] > > This test requires a Pinecone account on the Standard or Enterprise plan because it uses [import from object storage](/guides/data/import-data), which isn't available on the Starter or Builder plans. New users can sign up for the [Standard trial](/admin/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 activate the trial or [upgrade](/admin/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 > [!NOTE] > > 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. > [tab] Console > > 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**. > [tab] Code > > 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/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. > [tab] Console > > 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. > > > [!NOTE] > > > > 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. > [tab] Code > > Start the import: > > ```python Python theme={null} > from pinecone import Pinecone, ImportErrorMode > > pc = Pinecone(api_key="{{YOUR_API_KEY}}") > index = pc.index(name="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(name="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 > ``` > > > [!NOTE] > > > > 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. **1. Provision a VM** 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. > [!NOTE] > > 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). > [!NOTE] > > Create a VM that comes with Python 3.11 or higher. **2. Connect to the VM** Connect to the VM using SSH or the cloud provider's console. **3. Install Vector Search Bench (VSB)** [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 ``` **4. Benchmark your Pinecone index** 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. > [!NOTE] > > 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** | **1. Import costs** 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. **2. Query costs** A query uses 1 [read unit (RU)](/guides/cost/understand-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. **3. Storage costs** 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. **4. Total costs** 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/indexes/manage-indexes#delete-an-index) to avoid incurring unnecessary costs. # Bring Your Own Cloud (BYOC) overview 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. 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. ## Architecture ![BYOC architecture in which the Pinecone data plane, Kubernetes cluster, FoundationDB, object storage, and DNS run in a VPC in your AWS, GCP, or Azure account. The cluster pulls operations from the Pinecone-managed control plane, and only metrics and traces leave the cluster.](https://mintcdn.com/pinecone/ZVOnQqdJdQzJQn6W/images/byoc-architecture-light.svg?fit=max\&auto=format\&n=ZVOnQqdJdQzJQn6W\&q=85\&s=d94db2a849aca635dfb739d339edb48d) 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). Cluster metadata lives in FoundationDB, which runs inside your Kubernetes cluster, so there's no managed database to operate. * 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, that console CMEK flow doesn't apply. Your vectors and index data are stored in *your* cloud account (for example, object storage and block storage), so 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, you can supply your KMS key where the template supports it. For the current options, see the [pulumi-pinecone-byoc README](https://github.com/pinecone-io/pulumi-pinecone-byoc). ## Limitations Some features available in the standard Pinecone service aren't 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/indexes/index-data-overview#integrated-embedding) isn't supported, because it relies on models Pinecone hosts outside your cloud account. * If an index has a [private endpoint](/guides/production/bring-your-own-cloud/connect-and-manage#connect-over-a-private-endpoint), you can't read or write its data from the index browser in the Pinecone console. * The Pinecone CLI can't run data plane operations (queries, upserts, fetches), though its control plane operations (create, list, delete indexes) work as expected. * You can't import from private cloud storage buckets unless the bucket is in the same cloud account as your BYOC deployment. * On-demand indexes in an environment share the pool, so per-index rate limits prevent a busy index from slowing down the others. If one index needs more capacity than the pool can share, create it as a dedicated read nodes index. To [monitor with Prometheus](/guides/production/monitor-performance#monitor-with-prometheus), you must configure Prometheus within your VPC. ## Pricing Your Pinecone bill for a BYOC environment has two parts: a flat platform fee, and a rate for each node you run, across both the shared on-demand pool and your dedicated read nodes indexes. Separately, you pay your cloud provider directly for the underlying infrastructure (Kubernetes nodes, object storage, block storage, networking, etc.). ``` Pinecone bill = platform fee + (node rate × number of nodes) ``` | Term | Description | | :- | :- | | **Platform fee** | Flat monthly fee for each BYOC environment. Covers the always-on Pinecone components that serve writes and control operations, plus support. | | **Node rate** | Monthly rate for each node running in your cluster, metered in node hours. It applies to the nodes of the on-demand pool (`od1`) and to the [dedicated read nodes](/guides/optimize/dedicated-read-nodes/concepts#node-types) of your dedicated read nodes indexes (`b1` or `t1`). The rate varies by node type. Unlike the standard service, it's the same in every cloud and region. | | **Number of nodes** | The nodes in the on-demand pool, plus the sum of [shards](/guides/optimize/dedicated-read-nodes/concepts#shards) × [replicas](/guides/optimize/dedicated-read-nodes/concepts#replicas) across every dedicated read nodes index in the environment. Counted separately for each node type. | If an environment runs more than one node type, calculate the node cost for each type and add the results. The on-demand pool starts with two `od1` nodes and is billed whether or not you create on-demand indexes. Creating on-demand indexes doesn't add nodes, because they share the pool, so you pay for more `od1` nodes only when the pool grows beyond its capacity. Each dedicated read nodes index adds its `shards × replicas`. Unlike [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview#cost) in the standard service, BYOC has no separate Pinecone charges for storage or writes. That data lives in your own cloud account, so you pay your cloud provider for it instead of Pinecone. > [!TIP] > > For current rates and help sizing your BYOC environment, [contact us](https://www.pinecone.io/contact/). ### Example An environment with one dedicated read nodes index using two shards and two replicas runs four `b1` nodes in addition to the on-demand pool, which starts with two nodes. Its monthly bill is the platform fee, plus four times the `b1` node rate, plus two times the `od1` node rate (the starting pool), plus what you pay your cloud provider. Adding on-demand indexes to that environment doesn't change the bill until the pool needs more nodes. ### Metering and billing The Pinecone BYOC agent running in your cluster measures node usage, periodically reporting which nodes are provisioned. Billing follows the agent heartbeat connection to Pinecone's control plane: * When Pinecone receives heartbeats, you're billed for the nodes 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. > [!NOTE] > > Pinecone bills for provisioned nodes, not query volume. You're billed for nodes running in your cluster, including the on-demand pool, whether they're idle, actively processing queries, or experiencing errors. ## FAQs Answers to common questions about BYOC: > [accordion] Does Pinecone have access to my cloud account? > > No. BYOC uses a zero-access model, so Pinecone never needs direct access to your infrastructure. Specifically: > > * Pinecone does not need SSH, VPN, inbound access, or a standing cross-account role in your cloud account. > * 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. Pinecone monitors cluster health through operational metrics such as CPU and latency, without seeing your data. You choose what logs to share with [Pinecone support](https://app.pinecone.io/organizations/-/settings/support/ticket). > [accordion] What is the difference between on-demand and dedicated read nodes in BYOC? > > On-demand indexes share one pool of nodes that starts with two `od1` nodes, and Pinecone adds nodes when you need more capacity. Each dedicated read nodes index gets its own nodes. For how the two modes differ, see [On-demand vs. dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview#on-demand-vs-dedicated-read-nodes). > [accordion] Can I use on-demand indexes in an existing BYOC environment? > > Yes. On-demand is available in new and existing BYOC environments on AWS, GCP, and Azure. If on-demand isn't available in your environment, contact your Pinecone account team to enable it. > [accordion] What data leaves my 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. > [accordion] What is the difference between BYOC and Pinecone's standard service? > > 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. For a cost breakdown, see [Pricing](#pricing). > [accordion] How does authentication work? > > 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. > [accordion] How is data secured in BYOC? > > 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). > [accordion] Which cloud providers does BYOC support? > > BYOC is available on AWS, GCP, and Azure. > [accordion] What happens if I destroy the cluster before deleting indexes? > > Indexes cannot be properly terminated if the cluster is destroyed first. Always delete indexes via the Pinecone API or console before running `pulumi destroy`. > [accordion] What is the **SLI** project in my organization? > > 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. ## Next steps * [Deploy BYOC](/guides/production/bring-your-own-cloud/deploy) # Connect to and manage BYOC Source: https://docs.pinecone.io/guides/production/bring-your-own-cloud/connect-and-manage Connect to your Pinecone BYOC indexes over public or private networking, and manage, monitor, and tear down your BYOC deployment. Once your BYOC environment is deployed, connect to your indexes over public or private networking, then monitor and maintain the deployment. ## Connect to your index How you connect to your indexes for 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 depends on your network access mode. ### Connect over the public endpoint 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. ### Connect over a private endpoint With public access disabled, you can only connect from within your VPC via private connectivity. 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: > [tab] AWS > > **1. Create a VPC endpoint** > > 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. > > **2. Select network settings** > > For **Network settings**, select the VPC for your BYOC deployment. > > **3. Enable DNS name** > > In **Additional settings**, select **Enable DNS name** to allow you to access your indexes using a DNS name. > [tab] GCP > > **1. Create a private endpoint** > > 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. > > **2. Create a private DNS zone** > > 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. > > **3. Add a resource record set** > > 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. > [tab] Azure > > **1. Create a 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. > > **2. Create a private DNS zone** > > 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. > > **3. Add a wildcard A record** > > 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 Pinecone handles upgrades, scaling, and maintenance through the in-cluster agent. You monitor the deployment and tear it down when you no longer need it. ### 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: > [accordion] Pinecone console > > View index metrics (read/write units, latency, storage) in the Pinecone console. Control plane operations and metrics work regardless of your network access mode. > [accordion] Prometheus > > To use [Prometheus](/guides/production/monitor-performance#monitor-with-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. > [accordion] Audit logs > > 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: > [!WARNING] > > 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**: S3 buckets * **GCP**: GCS buckets * **Azure**: storage accounts # Create an index in BYOC Source: https://docs.pinecone.io/guides/production/bring-your-own-cloud/create-an-index Create an index in your Pinecone BYOC environment using the standard Pinecone API. Once your BYOC environment is [deployed](/guides/production/bring-your-own-cloud/deploy), you can create indexes and read/write data using the standard Pinecone API. 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](/guides/production/bring-your-own-cloud/connect-and-manage#connect-to-your-index). > [!NOTE] > > BYOC supports both on-demand and [dedicated read nodes (DRN)](/guides/optimize/dedicated-read-nodes/overview) indexes. > > * On-demand indexes and their namespaces share one pool of nodes in your BYOC environment. > * DRN indexes each get their own nodes, which you size with shards and replicas when you create the index. > > Both index types support vector search and [full-text search](/guides/search/full-text-search). To create an index in your BYOC environment, set these fields in the create request: * `deployment.deployment_type`: `byoc` * `deployment.environment`: The environment name from the [deployment output](/guides/production/bring-your-own-cloud/deploy) * `read_capacity.mode`: `OnDemand` for an on-demand index, or `Dedicated` for a DRN index The following examples use the API and SDKs. > [!TIP] > > You can also create either index type in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/create-index/): select the **BYOC** tab under **Capacity mode**, set **Read capacity** to **On-demand** or **Dedicated read nodes**, and enter your **Environment ID**. ## Create a DRN index A DRN index runs on its own set of nodes. Set the node type, shards, and replicas in `read_capacity`. ```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: 2026-07" \ -d '{ "name": "example-byoc-index", "deployment": { "deployment_type": "byoc", "environment": "aws-us-east-1-26bf.byoc" }, "schema": { "fields": { "title": { "type": "string", "full_text_search": {} }, "body": { "type": "string", "full_text_search": {} }, "embedding": { "type": "dense_vector", "dimension": 1536, "metric": "cosine" } } }, "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 pc = Pinecone(api_key="YOUR_API_KEY") pc.indexes.create( name="example-byoc-index", schema={ "fields": { "title": {"type": "string", "full_text_search": {}}, "body": {"type": "string", "full_text_search": {}}, "embedding": {"type": "dense_vector", "dimension": 1536, "metric": "cosine"}, } }, deployment={ "deployment_type": "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", ) ``` ## Create an on-demand index An on-demand index sets no shards or replicas, because it runs on the shared on-demand pool. ```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: 2026-07" \ -d '{ "name": "example-byoc-on-demand-index", "deployment": { "deployment_type": "byoc", "environment": "aws-us-east-1-26bf.byoc" }, "schema": { "fields": { "title": { "type": "string", "full_text_search": {} }, "body": { "type": "string", "full_text_search": {} }, "embedding": { "type": "dense_vector", "dimension": 1536, "metric": "cosine" } } }, "read_capacity": { "mode": "OnDemand" }, "deletion_protection": "disabled" }' ``` ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.indexes.create( name="example-byoc-on-demand-index", schema={ "fields": { "title": {"type": "string", "full_text_search": {}}, "body": {"type": "string", "full_text_search": {}}, "embedding": {"type": "dense_vector", "dimension": 1536, "metric": "cosine"}, } }, deployment={ "deployment_type": "byoc", "environment": "aws-us-east-1-26bf.byoc", }, read_capacity={"mode": "OnDemand"}, deletion_protection="disabled", ) ``` ## Next steps * [Connect to and manage your BYOC indexes](/guides/production/bring-your-own-cloud/connect-and-manage) # Deploy BYOC Source: https://docs.pinecone.io/guides/production/bring-your-own-cloud/deploy Deploy Pinecone BYOC into your own AWS, GCP, or Azure account with the setup wizard and Pulumi, then verify the deployment. Deploy the Pinecone BYOC data plane into your own AWS, GCP, or Azure account using the setup wizard and Pulumi, then verify it's running. ## 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` isn't sufficient because BYOC creates IAM roles and policies. * **GCP**: `roles/owner`. `roles/editor` isn't sufficient because BYOC creates IAM service accounts and bindings. * **Azure**: `Owner` on the subscription. `Contributor` isn't 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) > [!NOTE] > > 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 your environment To deploy BYOC, follow these steps: ### 1. Run the setup wizard 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. > [accordion] Setup wizard prompts > > 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 object 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. > [accordion] Generated configuration file > > The wizard creates a `Pulumi..yaml` file with configurable options. The options vary by cloud provider: > > > [tab] AWS > > > > | 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 S3 buckets 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 | `{}` | > > > [tab] GCP > > > > | 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 GCS buckets from accidental deletion | `true` | > > | `public-access-enabled` | Enable public endpoint (`false` = Private Service Connect only) | `true` | > > | `labels` | Custom labels for all GCP resources | `{}` | > > > [tab] Azure > > > > | 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 storage accounts 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`. > [accordion] Programmatic usage > > 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. ### 2. Deploy the infrastructure 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. > [accordion] Infrastructure provisioned > > 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) | > | **Block storage** | EBS volumes | Persistent Disk | Managed Disks | > | **Metadata store** | FoundationDB (in-cluster) | FoundationDB (in-cluster) | FoundationDB (in-cluster) | > | **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. ### 3. Verify the deployment Configure `kubectl` to connect to your cluster using the command from the deployment output: > [tab] AWS > > ```bash theme={null} > aws eks update-kubeconfig --region --name > ``` > [tab] GCP > > ```bash theme={null} > gcloud container clusters get-credentials --region --project > ``` > [tab] Azure > > ```bash theme={null} > az aks get-credentials --resource-group --name > ``` This 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. ## Troubleshooting Common issues and how to resolve them: > [accordion] Preflight check failures > > 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.Storage`, `Microsoft.Network`, `Microsoft.KeyVault`, `Microsoft.ManagedIdentity`, `Microsoft.Authorization` | > | Required APIs (GCP only) | Enable Compute Engine, GKE, Cloud Storage, and Cloud DNS | > [accordion] Deployment failures > > If `pulumi up` fails partway through: > > ```bash theme={null} > pulumi refresh # Sync state with actual resources > pulumi up # Retry deployment > ``` > [accordion] Cluster access issues > > Ensure your cloud credentials match the account where the cluster is deployed: > > > [tab] AWS > > > > ```bash theme={null} > > aws sts get-caller-identity > > ``` > > > [tab] GCP > > > > ```bash theme={null} > > gcloud auth list > > gcloud config get-value project > > ``` > > > [tab] Azure > > > > ```bash theme={null} > > az account show > > ``` > [accordion] Index stuck in terminating state > > 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. ## Next steps * [Create an index in your BYOC environment](/guides/production/bring-your-own-cloud/create-an-index) # 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. > [!NOTE] > > 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. > [tab] Grant access to key in 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). > > > [accordion] Explicit regions + external ID > > > > ```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" > > } > > } > > } > > ] > > } > > ``` > > > [accordion] Explicit regions + no external ID > > > > ```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" > > } > > ] > > } > > ``` > > > [accordion] All regions + external ID > > > > ```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_*" > > } > > } > > } > > ] > > } > > ``` > > > [!NOTE] > > > > 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). > [tab] Grant access to keys outside 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 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**. > [!NOTE] > > 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). > [!NOTE] > > **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. > [!WARNING] > > 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**. > [!WARNING] > > 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/indexes/back-up-an-index) are unavailable for indexes created in a CMEK-enabled project. * You can't change a key once it's 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. [Private endpoints](/admin/security/security-overview#private-endpoints) let your applications reach Pinecone indexes through AWS PrivateLink or Azure Private Link, so traffic between your network and Pinecone stays off the public internet. * Private endpoints carry [data plane](/guides/get-started/architecture#data-plane) traffic only. [Control plane](/guides/get-started/architecture#control-plane) requests, such as creating or describing an index, still go over the public internet. * Each private endpoint belongs to one project and connects only to that project's indexes in one region. You can add up to 10 private endpoints per project. ## Before you begin Make sure you have the following: * A [Pinecone Enterprise plan](https://www.pinecone.io/pricing/) * The owner role in the Pinecone project you want to connect to * A [serverless index](/guides/indexes/create-an-index#create-a-serverless-index) in one of the regions listed in [step 1](#1-create-a-private-endpoint-in-your-cloud-provider) > [tab] AWS > > * Access to the [AWS console](https://console.aws.amazon.com/console/home) > * An [Amazon VPC](https://docs.aws.amazon.com/vpc/latest/userguide/create-vpc.html#create-vpc-and-other-resources) in the same region as your index > [tab] Azure > > * Access to the [Azure portal](https://portal.azure.com) > * An [Azure VNet](https://learn.microsoft.com/en-us/azure/virtual-network/quick-create-portal) in the same region as your index, with a subnet whose **Private endpoint network policies** setting is **Disabled** ## Set up a private endpoint ### 1. Create a private endpoint in your cloud provider Create an endpoint in your VPC or VNet that connects to Pinecone's service in your index's region: > [tab] AWS > > 1. In the [Amazon VPC console](https://console.aws.amazon.com/vpc/), go to **Endpoints** and click **Create endpoint**. > > 2. For **Type**, select **Endpoint services that use NLBs and GWLBs**. > > 3. For **Service name**, enter the service name for your index's region, and then click **Verify service**: > > | 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` | > > 4. For **VPC**, select the VPC your clients connect from. > > 5. (Optional) In **Additional settings**, select **Enable DNS name**. This lets clients in the VPC resolve Pinecone's private DNS names without extra setup. It requires [DNS hostnames and DNS resolution](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html#vpc-dns-updating) to be enabled on the VPC. If you leave it off, or clients outside the VPC need to connect, you'll set up DNS yourself in [step 3](#3-configure-dns). > > 6. Select the **Subnets** for the endpoint, and select **Security groups** that allow inbound HTTPS (port 443) from your clients. > > 7. Click **Create endpoint**. > > 8. Copy the **VPC endpoint ID** (e.g., `vpce-XXXXXXX`). You'll enter it in Pinecone in the next step. > [tab] Azure > > 1. In the [Azure portal](https://portal.azure.com), search for **Private Link** and select **Private Link Center**. Then go to **Private endpoints** and click **Create**. > > 2. Select your **Subscription** and **Resource group**, enter a **Name** for the private endpoint, and select the **Region** that matches your index. Then click **Next: Resource**. > > 3. For **Connection method**, select **Connect to an Azure resource by resource ID or alias**, and enter the **Resource ID or alias** for your index's region: > > | Index region | Private Link Service alias | > | - | - | > | `eastus2` (Virginia) | `pinecone.bdbc7759-0243-46c1-af51-794c4602745b.eastus2.azure.privatelinkservice` | > > 4. Click **Next: Virtual Network**, and select the **Virtual network** and **Subnet** for the private endpoint. > > 5. Click **Next: DNS**, and skip this tab. You'll set up DNS in [step 3](#3-configure-dns). > > 6. Click **Next: Tags**, then **Review + create**, and then **Create**. > > 7. After Azure creates the private endpoint, open it, go to **Properties**, and copy the **Resource ID** (e.g., `/subscriptions//resourceGroups//providers/Microsoft.Network/privateEndpoints/`). You'll enter it in Pinecone in the next step. ### 2. Add a private endpoint in Pinecone Add the endpoint to your Pinecone project so Pinecone accepts connections through it: 1. In the [Pinecone console](https://app.pinecone.io/organizations/-/projects), select your project and go to **Settings > Network**. 2. On the **PRIVATE ENDPOINTS** tab, click **Add an endpoint**. 3. Select your cloud provider and your index's region, and then click **Next**. 4. Enter the ID you copied in [step 1](#1-create-a-private-endpoint-in-your-cloud-provider), and then click **Next**: * **AWS**: The VPC endpoint ID. * **Azure**: The private endpoint's resource ID. 5. Leave **Restrict access to only private endpoints** off for now. Turning it on cuts off internet access to the project before your private endpoint works. You can [turn it on later](#restrict-access-to-private-endpoints). 6. Click **Finish setup**. ### 3. Configure DNS Clients reach an index through its [private endpoint URL](#4-connect-to-your-index), such as `docs-example-jl7boae.svc.private.aped-4627-b74a.pinecone.io`. Public DNS doesn't resolve these names, so DNS on your network must resolve them to your private endpoint's IP address. Clients must connect by hostname rather than IP address, because Pinecone's TLS certificate is issued for the hostname, not the IP address. Each region has one private DNS zone. A single wildcard record (`*`) in that zone covers every index in the region: | Cloud | Index region | Private DNS zone | | - | - | - | | AWS | `us-east-1` (N. Virginia) | `private.aped-4627-b74a.pinecone.io` | | AWS | `us-west-2` (Oregon) | `private.apw5-4e34-81fa.pinecone.io` | | AWS | `eu-west-1` (Ireland) | `private.apu-57e2-42f6.pinecone.io` | | AWS | `eu-central-1` (Frankfurt) | `private.apec-a2ee-38c6.pinecone.io` | | AWS | `ap-southeast-1` (Singapore) | `private.aps-d9bb-582b.pinecone.io` | | Azure | `eastus2` (Virginia) | `private.eastus2-5e25.prod-azure.pinecone.io` | Clients also need a network route to the private endpoint's IP address on port 443. For clients outside the VPC or VNet, such as on-premises servers, that usually means a VPN, AWS Direct Connect, Azure ExpressRoute, or network peering. > [tab] AWS > > If you selected **Enable DNS name** when you created the VPC endpoint, clients in that VPC already resolve Pinecone's private DNS names. Set up DNS yourself if you turned that option off, or if clients outside the VPC need to connect: > > * **Route 53 private hosted zone**: Create a [private hosted zone](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zone-private-creating.html) named after your region's private DNS zone and associate it with your VPCs. Then add a wildcard record (`*`) that [routes traffic to the VPC endpoint](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-vpc-interface-endpoint.html). > * **Your own DNS server**: On your organization's DNS server, create a zone named after your region's private DNS zone. Add a wildcard CNAME record (`*`) that points to the VPC endpoint's regional DNS name, which has the form `vpce-XXXXXXX.vpce-svc-XXXXXXX.REGION.vpce.amazonaws.com`. AWS publishes that name in public DNS, and it resolves to the endpoint's private IP addresses. To get it, run `aws ec2 describe-vpc-endpoints --vpc-endpoint-ids VPC_ENDPOINT_ID --query 'VpcEndpoints[*].DnsEntries'`. The first entry is the regional DNS name. > * **Forward to Route 53**: If you selected **Enable DNS name**, you can keep AWS as the source of these records instead. Create a [Route 53 Resolver inbound endpoint](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resolver-forwarding-inbound-queries.html) in the VPC, and then add a conditional forwarder on your DNS server that sends queries for the private DNS zone to the inbound endpoint's IP addresses. > [tab] Azure > > Azure doesn't resolve Pinecone's private DNS names automatically, so you must set up DNS. First, find your private endpoint's IP address. In the Azure portal, open your private endpoint, and on its **Overview** page, select its network interface. The network interface's **Overview** page shows the **Private IP address** (e.g., `172.30.0.6`). > > Then set up DNS in one of the following ways. > > #### Use an Azure Private DNS zone > > Use this option if your clients use Azure-provided DNS. > > 1. Create an [Azure Private DNS zone](https://learn.microsoft.com/en-us/azure/dns/private-dns-getstarted-portal) named `private.eastus2-5e25.prod-azure.pinecone.io`. > 2. [Link the zone](https://learn.microsoft.com/en-us/azure/dns/private-dns-virtual-network-links) to the VNet where you created the private endpoint, and to any other VNets whose clients connect to Pinecone. > 3. Add a wildcard A record (`*.private.eastus2-5e25.prod-azure.pinecone.io`) that points to your private endpoint's IP address. > > #### Use your own DNS server > > Use this option if your organization runs its own DNS server. > > 1. On your DNS server, create a zone named `private.eastus2-5e25.prod-azure.pinecone.io`. > 2. Add a wildcard A record (`*.private.eastus2-5e25.prod-azure.pinecone.io`) that points to your private endpoint's IP address. > 3. Make sure the clients that connect to Pinecone use this DNS server. > > #### Forward to an Azure Private DNS zone > > Use this option if your organization runs its own DNS but manages private endpoint records in Azure. > > 1. Set up an [Azure Private DNS zone](#use-an-azure-private-dns-zone) as described above. > 2. Create an [Azure DNS Private Resolver](https://learn.microsoft.com/en-us/azure/dns/dns-private-resolver-overview) with an inbound endpoint in a VNet that's linked to the zone. > 3. On your DNS server, add a conditional forwarder that sends queries for `private.eastus2-5e25.prod-azure.pinecone.io` to the inbound endpoint's IP address. > > For more on these patterns, see [Azure Private Endpoint DNS integration](https://learn.microsoft.com/en-us/azure/private-link/private-endpoint-dns-integration). > > > [!NOTE] > > > > A private endpoint keeps its IP address for as long as it exists. If you point an A record at that address and later delete and re-create the endpoint, update the record with the new address. To check your setup, look up your index's private endpoint URL from a client machine. Replace the example host with your index's **Private host** value from [step 4](#4-connect-to-your-index): ```bash Terminal theme={null} nslookup docs-example-jl7boae.svc.private.aped-4627-b74a.pinecone.io ``` The response should return your private endpoint's IP address. If the lookup fails or returns a different address, the client isn't using the DNS server or zone you configured. ### 4. Connect to your index To send data operations through your private endpoint, target the index by its private endpoint URL instead of its standard host. The only difference is that `.svc.` becomes `.svc.private.`. You can get the private endpoint URL for an index from the Pinecone console or API. > [tab] Console > > 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 **Private host** value. > [tab] API > > To get the private endpoint URL for an index from the API, use the [Describe an 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/v7/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: 2026-07" > ``` > > 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 {4} theme={null} > { > "name": "docs-example", > "host": "docs-example-jl7boae.svc.aped-4627-b74a.pinecone.io", > "private_host": "docs-example-jl7boae.svc.private.aped-4627-b74a.pinecone.io", > "status": { > "ready": true, > "state": "Ready" > }, > "deployment": { > "deployment_type": "managed", > "region": "us-east-1", > "cloud": "aws", > "environment": "aped-4627-b74a" > }, > "read_capacity": { > "mode": "OnDemand", > "status": { > "state": "Ready", > "current_shards": null, > "current_replicas": null > } > }, > "schema": { > "fields": { > "embedding": { > "type": "dense_vector", > "description": null, > "dimension": 1536, > "metric": "cosine" > } > } > }, > "tags": { > "environment": "production" > }, > "deletion_protection": "disabled" > } > ``` > [!NOTE] > > If you [restrict access to private endpoints](/guides/production/configure-private-endpoints#restrict-access-to-private-endpoints), requests that don't come through a private endpoint get an `Unauthorized` response. Requests through a private endpoint that isn't registered to the index's project also get `Unauthorized`. ## Restrict access to private endpoints After your private endpoint works, you can turn off internet access to the project. Then only requests that come through a private endpoint can read or write the project's indexes. > [!WARNING] > > This setting applies to the whole project. Any application that reaches an index in the project over the internet stops working. 1. In the [Pinecone console](https://app.pinecone.io/organizations/-/projects), select your project and go to **Settings > Network**. 2. On the **ACCESS** tab, turn on **Restrict access to only private endpoints**. 3. Click **Confirm and proceed**. To turn internet access back on, turn the toggle off. ## Manage private endpoints To view a project's private endpoints, open the [Pinecone console](https://app.pinecone.io/organizations/-/projects), select the project, and go to **Settings > Network**. The **PRIVATE ENDPOINTS** tab lists each endpoint's ID, cloud, and region. To delete a private endpoint: 1. On the **PRIVATE ENDPOINTS** tab, open the **Actions** menu for the endpoint and click **Delete**. 2. Enter the endpoint ID to confirm, and then click **Delete Endpoint**. Deleting a private endpoint in Pinecone doesn't delete the endpoint in your AWS or Azure account. Delete it there separately if you no longer need it. # Data deletion on Pinecone Source: https://docs.pinecone.io/guides/production/data-deletion Learn how Pinecone permanently deletes customer data, including soft deletion, the 90-day retention window, and secure erasure of records and indexes. Pinecone follows a secure process to ensure that customer data is permanently deleted from our system. This page gives an overview of the process. As defined in the [Master Subscription Agreement](https://www.pinecone.io/legal/master-subscription-agreement/), customer data is data that you provide to Pinecone through the services of the Pinecone system, or such data provided on your behalf by connected systems. This includes objects such as [records](/guides/get-started/key-terms#record), [indexes](/guides/get-started/key-terms#index), [backups](/guides/get-started/key-terms#backup), [projects](/guides/get-started/key-terms#project), [API keys](/guides/get-started/key-terms#api-key), [users](/admin/organizations/manage-organization-members), [assistants](/guides/assistant/overview), and [organizations](/guides/get-started/key-terms#organization). ## Deletion request The deletion of customer data begins when you initiate a deletion request through the Pinecone API, console, or a connected service. A deletion request can delete a single resource, such as a record, or can delete a resource and all its dependent resources, such as an index and all its records. Deletion of your customer data also occurs automatically when you end your relationship with Pinecone. If your account is [deactivated for continued non-payment](/admin/billing/non-payment-account-deactivation), account data is retained for 30 days before permanent deletion. ## Soft deletion After you initiate a deletion request, Pinecone marks the data for deletion. The data isn't immediately removed from the system. Instead, Pinecone retains the data for a maximum of 90 days. During this period, the data isn't accessible to you or any other user. ## Permanent deletion Before the end of the 90-day retention window, Pinecone permanently deletes the data from its system. Once the data is permanently deleted, it's no longer recoverable. > [!NOTE] > > Pinecone creates an [audit log](/admin/security/security-overview#audit-logs) of user, service account, and API events. Events are captured within two hours of occurrence and are retained for 90 days, after which they're permanently deleted. ## See also * [Delete records](/guides/data/delete-data) * [Delete an index](/guides/indexes/manage-indexes#delete-an-index) * [Delete a project](/admin/projects/manage-projects#delete-a-project) * [Delete an API key](/admin/projects/manage-api-keys#delete-an-api-key) * [Delete a user](/admin/projects/manage-project-members#remove-a-member) * [Delete an organization](/admin/organizations/delete-your-organization) * [Master Subscription Agreement](https://www.pinecone.io/legal/master-subscription-agreement/) # Error handling Source: https://docs.pinecone.io/guides/production/error-handling Handle Pinecone API errors with retry logic, exponential backoff, and best practices for 4xx client errors, 5xx server errors, and rate limit responses. This page covers how to read Pinecone API errors, catch them in your code, retry the ones that are transient, and stay within rate limits. ## Understand error types Pinecone uses [conventional HTTP response codes](/reference/api/errors) to indicate the success or failure of API requests: * **2xx codes** indicate success * **4xx codes** indicate client errors (issues with your request) * **5xx codes** indicate server errors (issues with Pinecone's servers) ### Client errors (4xx) Client errors indicate problems with your request. These errors typically require changes to your code or configuration: * **400 - Invalid Argument**: Your request contains invalid parameters. Check your request format and parameters. * **401 - Unauthenticated**: Your API key is missing or invalid. Verify your [API key](/admin/projects/manage-api-keys). * **402 - Payment Required**: Your account has a payment issue or may be deactivated for non-payment. Check your billing status in the [console](https://app.pinecone.io) and see [Account deactivation for non-payment](/admin/billing/non-payment-account-deactivation). * **403 - Forbidden**: You've exceeded a [quota](/reference/api/database-limits/object-limits) or hit [deletion protection](/guides/indexes/manage-indexes#configure-deletion-protection). * **404 - Not Found**: The requested resource doesn't exist. Verify the resource name and that it hasn't been deleted. * **409 - Already Exists**: You're trying to create a resource that already exists. * **429 - Too Many Requests**: You're being [rate-limited](/reference/api/database-limits/rate-limits). Implement [backoff and retry logic](#implement-retry-logic). ### Server errors (5xx) Server errors indicate temporary issues with Pinecone's infrastructure: * **500 - Unknown**: An internal server error occurred. * **502 - Bad Gateway**: The API gateway received an invalid response from a backend service. * **503 - Unavailable**: The service is currently unavailable. * **504 - Gateway Timeout**: The API gateway didn't receive a timely response from the backend server. This can occur due to slow requests or backend processing delays. These errors are usually transient, so [retry them with exponential backoff](#exponential-backoff). ## Capture errors ### Python SDK The Python SDK raises exceptions that you can catch and handle: ```python Python theme={null} from pinecone import Pinecone from pinecone.exceptions import PineconeException pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/target-an-index index = pc.index(host="INDEX_HOST") try: index.documents.upsert( namespace="articles", documents=[ {"_id": "doc1", "body": "Pinecone serverless indexes scale automatically with your workload."} ], ) except PineconeException as e: # Handle Pinecone-specific errors print(f"Pinecone error: {e}") except Exception as e: # Handle other errors print(f"Unexpected error: {e}") ``` See the [Python SDK documentation](https://sdk.pinecone.io/python/) for more details on exception handling. ### Node.js SDK The Node.js SDK uses standard JavaScript error handling: ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); try { // To get the unique host for an index, // see https://docs.pinecone.io/guides/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST', namespace: 'articles' }); await index.documents.upsert({ documents: [ { _id: 'doc1', body: 'Pinecone serverless indexes scale automatically with your workload.' }, ], }); } catch (error) { console.error('Error upserting data:', error); // Handle the error appropriately } ``` See the [Node.js SDK documentation](https://sdk.pinecone.io/typescript/) for more information. ### Other SDKs For error handling in other languages, see the documentation for your SDK: * [Go SDK](/reference/sdks/go/overview) * [Java SDK](/reference/sdks/java/overview) ## Implement retry logic For transient errors (5xx codes and 429 rate limiting), implement retry logic. Start with basic retries for simple use cases, or use exponential backoff for production systems. ### Basic retry logic For simple use cases, start with a basic retry loop with fixed delays: ```python Python theme={null} import time from pinecone.exceptions import PineconeException def simple_retry(func, max_retries=3, delay=2): """ Retry a function with a fixed delay between attempts. Args: func: Function to retry max_retries: Maximum number of retry attempts delay: Delay in seconds between retries """ for attempt in range(max_retries): try: return func() except PineconeException as e: # Retries every Pinecone error. For status-aware retries, see Exponential backoff. if attempt == max_retries - 1: raise # Last attempt, re-raise the exception print(f"Attempt {attempt + 1} failed, retrying in {delay}s...") time.sleep(delay) # Usage # `index` is an index connection. See https://docs.pinecone.io/guides/indexes/target-an-index documents = [ {"_id": "doc1", "body": "Pinecone serverless indexes scale automatically with your workload."} ] try: simple_retry(lambda: index.documents.upsert(namespace="articles", documents=documents)) except Exception as e: print(f"Failed after retries: {e}") ``` This basic approach works well for occasional transient errors, but for production systems with higher traffic, use exponential backoff instead. ### Exponential backoff Exponential backoff progressively increases the wait time between retries to avoid overwhelming the service: ```python Python theme={null} import time import random from pinecone.exceptions import PineconeException def exponential_backoff_retry(func, max_retries=5, base_delay=1, max_delay=60): """ Retry a function with exponential backoff. Args: func: Function to retry max_retries: Maximum number of retry attempts base_delay: Initial delay in seconds max_delay: Maximum delay between retries """ for attempt in range(max_retries): try: return func() except PineconeException as e: if attempt == max_retries - 1: raise # Last attempt, re-raise the exception # Get status code if available status_code = getattr(e, 'status_code', None) # Only retry on 5xx errors or 429 (rate limiting) if status_code and (status_code >= 500 or status_code == 429): # Calculate delay with exponential backoff and jitter delay = min(base_delay * (2 ** attempt), max_delay) jitter = random.uniform(0, delay * 0.1) # Add 10% jitter wait_time = delay + jitter print(f"Retry attempt {attempt + 1}/{max_retries} after {wait_time:.2f}s") time.sleep(wait_time) else: # Don't retry client errors (4xx except 429) raise # Usage # `index` is an index connection. See https://docs.pinecone.io/guides/indexes/target-an-index documents = [ {"_id": "doc1", "body": "Pinecone serverless indexes scale automatically with your workload."} ] try: exponential_backoff_retry(lambda: index.documents.upsert(namespace="articles", documents=documents)) except Exception as e: print(f"Failed after retries: {e}") ``` ### Built-in retries in the Go SDK The Go SDK has built-in retries with exponential backoff. Set a `RetryPolicy` on the client and it applies to both the REST (control/data/inference) and gRPC (data plane) clients. Over REST, the SDK retries 429 on every request, but it retries 5xx and transport errors only for idempotent methods such as GET, PUT, and DELETE, so it doesn't replay a request that might have already changed data. Documents API calls use POST, so they aren't retried on 5xx. To retry them, wrap them in your own retry loop, like the Python examples above. Searches are safe to retry, and so are upserts, because an upsert by `_id` replaces the whole document. The gRPC client also retries `UNAVAILABLE` and `RESOURCE_EXHAUSTED`. Other 4xx errors are never retried. ```go Go theme={null} package main import ( "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), RetryPolicy: pinecone.DefaultRetryPolicy(), // 3 retries, 500ms base, 30s cap, 2x backoff }) if err != nil { panic(err) } _ = pc } ``` To customize the behavior, construct a `RetryPolicy` with your own `MaxRetries`, `BaseDelay`, `MaxDelay`, and `BackoffMultiplier`. See the [Go SDK documentation](/reference/sdks/go/overview) for details. ### Retry best practices * **Add jitter**: Random variation in retry timing keeps many clients from retrying at the same moment. * **Set max retries**: Prevent infinite retry loops. * **Cap delay time**: Don't wait indefinitely between retries. * **Don't retry client errors**: 4xx errors (except 429) won't resolve with retries. * **Log retry attempts**: Track retry behavior for monitoring and debugging. ## Handle rate limits (429) When you receive a 429 error, you're being rate-limited. See [Rate limits](/reference/api/database-limits/rate-limits) for current limits. Rate limits protect your applications and the health of the serverless infrastructure. Most limits can be raised on request. If you need higher limits to scale, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. > [!NOTE] > > Indexes built on [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) aren't subject to read unit limits for query, fetch, list, and full-text search operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) guide. ### Best practices * Retry with [exponential backoff](#exponential-backoff). * Proactively [monitor request metrics](/guides/production/monitor-performance) and reduce the request rate if you're approaching limits. * Use [batching](/guides/data/upsert-data#upsert-in-batches) to reduce the number of requests. * For high-throughput needs, see [Increase throughput](/guides/optimize/increase-throughput). ## Get support If you've implemented error handling and retry logic but still see errors: 1. Review [Get help](/admin/support/contact-support) for how to file a ticket that gets a fast resolution. 2. Gather the following information: * Index name and project name * Error messages and stack traces * Timestamp of errors * Request and response examples (without sensitive data) * Whether the issue is reproducible 3. [Contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Ensure your [plan tier](https://www.pinecone.io/pricing/) provides the support SLA you need for production workloads. # Mock the Pinecone API for testing Source: https://docs.pinecone.io/guides/production/mock-the-api Run a local mock of the Pinecone API from its OpenAPI specs so tests and CI can exercise your Pinecone client code without an account or calls to Pinecone. > [!NOTE] > > Pinecone Local, the in-memory emulator, reached end of life on October 7, 2026. If you used it for testing, the mock in this guide covers request and error-handling tests. It doesn't cover tests that write data and read it back, or tests that need real search results. You can run a local mock of the Pinecone API from Pinecone's public [OpenAPI specs](https://github.com/pinecone-io/pinecone-api) using [Prism](https://github.com/stoplightio/prism), an open-source mock server. The mock checks each request against the spec, rejecting bad request bodies and missing headers, and answers with the example response from the spec. Use it in unit tests and CI to confirm that your code builds valid requests and handles responses and errors, without a Pinecone account or calls to Pinecone. The mock doesn't store anything, and every call returns the same canned response no matter what you send. If you upsert a document and then fetch or search for it, you get the spec's example document, not yours. So you can't use the mock to test a write followed by a read, or to test search relevance. Run those tests against a [separate project](/admin/projects/create-a-project) in your Pinecone account. ## Before you begin Ensure you have the following: * [Docker](https://docs.docker.com/get-started/get-docker/) with Docker Compose * [Git](https://git-scm.com/downloads) * The [Pinecone Python SDK](/reference/sdks/python/overview) v10 or later, or the [Pinecone Node.js SDK](/reference/sdks/node/overview) v9 or later ## Run the mock **1. Get the API specs** Clone the repository that holds Pinecone's OpenAPI specs. Each API version has its own directory, such as `2026-07`. ```bash Terminal theme={null} git clone --depth 1 https://github.com/pinecone-io/pinecone-api.git ``` **2. Define the mock services** The Pinecone API is split across three specs, so you run one Prism container for each. In the directory that contains `pinecone-api`, create a `docker-compose.yaml` file with the following content: ```yaml docker-compose.yaml theme={null} services: # Control plane: create, describe, list, and delete indexes pinecone-control-mock: image: stoplight/prism:5.14.3 platform: linux/amd64 command: mock -h 0.0.0.0 -p 5080 /specs/2026-07/db_control_2026-07.oas.yaml ports: - "5080:5080" volumes: - ./pinecone-api:/specs:ro # Data plane: upsert, query, fetch, and search data pinecone-data-mock: image: stoplight/prism:5.14.3 platform: linux/amd64 command: mock -h 0.0.0.0 -p 5081 /specs/2026-07/db_data_2026-07.oas.yaml ports: - "5081:5081" volumes: - ./pinecone-api:/specs:ro # Inference: embed and rerank pinecone-inference-mock: image: stoplight/prism:5.14.3 platform: linux/amd64 command: mock -h 0.0.0.0 -p 5082 /specs/2026-07/inference_2026-07.oas.yaml ports: - "5082:5082" volumes: - ./pinecone-api:/specs:ro ``` This guide uses the `2026-07` specs, the API version that the Pinecone Python SDK v10 and Pinecone Node.js SDK v9 send. Prism publishes images only for Intel and AMD processors (`linux/amd64`), with no ARM build. On a Mac with Apple silicon, Docker runs them under emulation. The `platform` setting makes that explicit and silences Docker's platform warning. > [!NOTE] > > Pin the Prism image to a version that starts. Every 5.15 image, including the `5` and `latest` tags, exits on startup with `TypeError: Cannot read properties of undefined (reading 'isPrimary')` on both Intel and Apple silicon. `5.14.3` is the newest version that works. **3. Start the mock** Start the three containers in the background: ```bash Terminal theme={null} docker compose up -d ``` Prism takes several seconds to load each spec. When all three are ready, `docker compose logs` shows a line like this for each port: ```text Output theme={null} pinecone-control-mock-1 | [4:00:17 AM] › [CLI] ▶ start Prism is listening on http://0.0.0.0:5080 ``` **4. Point the SDK at the mock** Set the client's host to the control-plane mock, and target the index by host with the data-plane mock. Any API key works, but the SDK requires one. In Python, use the HTTP client, not the gRPC client, because the mock doesn't serve gRPC. Don't target the index by name. The SDK would describe the index to look up its host, and the mock returns the spec's example host on `pinecone.io`, not the mock. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="test-key", host="http://localhost:5080") index = pc.index(host="http://localhost:5081") description = pc.indexes.describe("example-index") print(description.name) upserted = index.documents.upsert( namespace="example-namespace", documents=[{"_id": "article-1", "title": "Mocking APIs", "body": "Mock servers return canned responses."}], ) print(upserted.upserted_count) results = index.documents.search( namespace="example-namespace", top_k=3, score_by=[{"type": "text", "fields": ["body"], "query": "canned responses"}], ) print(results.matches[0].id) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'test-key', controllerHostUrl: 'http://localhost:5080' }); const index = pc.index({ host: 'http://localhost:5081', namespace: 'example-namespace' }); const description = await pc.describeIndex('example-index'); console.log(description.name); const upserted = await index.documents.upsert({ documents: [{ _id: 'article-1', title: 'Mocking APIs', body: 'Mock servers return canned responses.' }], }); console.log(upserted.upsertedCount); const results = await index.documents.search({ scoreBy: [{ type: 'text', fields: ['body'], query: 'canned responses' }], topK: 3, }); console.log(results.matches[0]._id); ``` All three calls succeed, and all three return the spec's examples instead of results based on your request. The index you described is named `my-index`, the upsert reports two documents even though you sent one, and the top match is `doc-1`: ```text Output theme={null} my-index 2 doc-1 ``` The legacy Vectors API methods, such as `upsert`, `query`, and `fetch`, work against the mock the same way. ## Mock inference calls The standalone embedding and reranking endpoints, such as `embed` and `rerank`, are in a separate spec, so they're served from a separate port. Create a second client with the inference mock as its host: ```python Python theme={null} from pinecone import Pinecone pc_inference = Pinecone(api_key="test-key", host="http://localhost:5082") result = pc_inference.inference.rerank( model="bge-reranker-v2-m3", query="What is the capital of France?", documents=["Paris is the capital of France.", "Berlin is the capital of Germany."], top_n=2, ) print(result.data[0].score) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pcInference = new Pinecone({ apiKey: 'test-key', controllerHostUrl: 'http://localhost:5082' }); const result = await pcInference.inference.rerank({ model: 'bge-reranker-v2-m3', query: 'What is the capital of France?', documents: ['Paris is the capital of France.', 'Berlin is the capital of Germany.'], topN: 2, }); console.log(result.data[0].score); ``` The top result's score is the spec's example score: ```text Output theme={null} 0.5 ``` ## Test error handling To test how your code handles API errors, ask Prism for a specific status code with the `Prefer` header. Prism returns that code for every request from a client that sets the header. Data-plane endpoints return any `4xx` or `5xx` code. Control-plane and inference endpoints return only the codes their spec lists. For any other code, Prism responds with a `404` that says the requested status code isn't defined. For more on handling errors, see [Error handling](/guides/production/error-handling). ### Example Return `503 Service Unavailable` from a document search to test your retry handling: ```python Python theme={null} from pinecone import Pinecone from pinecone.errors import ServiceError pc = Pinecone( api_key="test-key", host="http://localhost:5080", additional_headers={"Prefer": "code=503"}, ) index = pc.index(host="http://localhost:5081") try: index.documents.search( namespace="example-namespace", top_k=3, score_by=[{"type": "text", "fields": ["body"], "query": "canned responses"}], ) except ServiceError as e: print(f"Service unavailable: {e.status_code}") ``` ```javascript JavaScript theme={null} import { Pinecone, Errors } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'test-key', controllerHostUrl: 'http://localhost:5080', additionalHeaders: { Prefer: 'code=503' }, }); const index = pc.index({ host: 'http://localhost:5081', namespace: 'example-namespace' }); try { await index.documents.search({ scoreBy: [{ type: 'text', fields: ['body'], query: 'canned responses' }], topK: 3, }); } catch (e) { if (e instanceof Errors.PineconeMaxRetriesExceededError) { console.log(`Service unavailable: ${e.name}`); } else { throw e; } } ``` Both SDKs retry a `503` three times before they raise an error, so this test takes a few seconds. The Python SDK raises `ServiceError`, and the Node.js SDK raises `PineconeMaxRetriesExceededError`. ## Run the mock in CI In a [GitHub Actions](https://docs.github.com/en/actions) workflow, start the mock with Docker Compose as a step before your tests run. GitHub's `services` containers can't pass Prism its `mock` command or mount the specs, so you can't use them here. The following workflow assumes your repository has the `docker-compose.yaml` file from this guide at its root and your tests in a `tests` directory. It clones the specs, starts the mock, waits until all three ports respond, and runs the tests: ```yaml .github/workflows/test.yaml theme={null} name: Test on: push: branches: [main] pull_request: jobs: test: runs-on: ubuntu-latest steps: - name: Check out repository code uses: actions/checkout@v7 - name: Get the Pinecone API specs run: git clone --depth 1 https://github.com/pinecone-io/pinecone-api.git - name: Start the mock run: | docker compose up -d for port in 5080 5081 5082; do timeout 60 sh -c "until curl -s localhost:$port > /dev/null; do sleep 1; done" done - name: Set up Python uses: actions/setup-python@v7 with: python-version: "3.12" - name: Install dependencies run: pip install "pinecone>=10" "pytest" - name: Run tests run: pytest tests/ - name: Show mock logs on failure if: failure() run: docker compose logs ``` ## Limitations Some calls fail against the mock even though they work against Pinecone: * **Upserting records into a legacy integrated index**: The legacy Records API methods, `upsert_records` and `upsertRecords`, send newline-delimited JSON, which Prism can't parse, so the mock rejects them with a `422`. Searching a legacy integrated index works, and so does upserting into a document index. * **Embedding with the Node.js SDK**: The mock's embed response doesn't include a valid `vector_type` for each embedding, so `inference.embed()` throws `No variant of Embedding exists with 'vectorType=undefined'`. Embedding works with the Python SDK, and reranking works with both. ## Stop the mock Stop and remove the containers: ```bash Terminal theme={null} docker compose down ``` # Monitor performance Source: https://docs.pinecone.io/guides/production/monitor-performance Monitor Pinecone index performance metrics (query latency, throughput, and errors) in the Pinecone console or via Prometheus and Datadog. 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. These are performance metrics, not cost. For per-index cost, see [Download a usage report](/admin/billing/download-usage-report), which breaks usage down by individual index. ## Monitor in 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. ## Monitor with Datadog To monitor Pinecone with Datadog, use Datadog's [Pinecone integration](/integrations/datadog). > [!NOTE] > > This feature is available on the [Builder, Standard, and Enterprise plans](https://www.pinecone.io/pricing/). ## Monitor with Prometheus > [!NOTE] > > This feature is available on the [Builder, 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 serverless indexes in 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: > [!NOTE] > > This method uses [HTTP service discovery](https://prometheus.io/docs/prometheus/latest/http_sd/) to automatically discover and target all serverless indexes across all regions in a project. ```YAML theme={null} global: scrape_interval: 15s scrape_configs: - job_name: 'pinecone-serverless-metrics' http_sd_configs: - url: https://api.pinecone.io/prometheus/projects/PROJECT_ID/metrics/discovery refresh_interval: 1m authorization: type: Bearer credentials: API_KEY authorization: type: Bearer credentials: API_KEY ``` * Replace `PROJECT_ID` with the unique ID of the project you want to monitor. You can [find the project ID](/admin/projects/projects-overview#project-ids) in the Pinecone console. * Replace both instances of `API_KEY` with an API key for the project you want to monitor. The first instance is for service discovery, and the second instance is for the discovered targets. If necessary, you can [create an new API key](/admin/projects/manage-api-keys) in the Pinecone console. 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_db_record_total` | gauge | The total number of records in the index. | | `pinecone_db_storage_size_bytes` | gauge | The total size of the index in bytes. | | `pinecone_db_op_upsert_count` | counter | The number of [upsert](/guides/data/upsert-data) requests. | | `pinecone_db_op_upsert_duration_sum` | counter | The total time taken processing [upsert](/guides/data/upsert-data) requests in milliseconds. | | `pinecone_db_op_query_count` | counter | The number of [query](/guides/search/search-overview) requests. | | `pinecone_db_op_query_duration_sum` | counter | The total time taken processing [query](/guides/search/search-overview) requests in milliseconds. | | `pinecone_db_op_fetch_count` | counter | The number of [fetch](/guides/data/fetch-data) requests. | | `pinecone_db_op_fetch_duration_sum` | counter | The total time taken processing [fetch](/guides/data/fetch-data) requests in milliseconds. | | `pinecone_db_op_update_count` | counter | The number of [update](/guides/data/update-data) requests. | | `pinecone_db_op_update_duration_sum` | counter | The total time taken processing [update](/guides/data/update-data) requests in milliseconds. | | `pinecone_db_op_delete_count` | counter | The number of [delete](/guides/data/delete-data) requests. | | `pinecone_db_op_delete_duration_sum` | counter | The total time taken processing [delete](/guides/data/delete-data) requests in milliseconds. | | `pinecone_db_op_list_count` | counter | The number of [list](/guides/data/list-record-ids) requests. | | `pinecone_db_op_list_duration_sum` | counter | The total time taken processing [list](/guides/data/list-record-ids) requests in milliseconds. | | `pinecone_db_write_unit_count` | counter | The total number of [write units](/guides/cost/understand-cost#write-units) consumed by an index. | | `pinecone_db_read_unit_count` | counter | The total number of [read units](/guides/cost/understand-cost#read-units) consumed by an index. | | `pinecone_db_scheduled_backup_failure_total` | counter | The number of terminal failures for [scheduled backup](/guides/indexes/back-up-an-index) create operations. | | `pinecone_db_drn_cpu_usage_percent` | gauge | The CPU usage percentage for a [dedicated read node](/guides/optimize/dedicated-read-nodes/overview) shard, averaged across replicas. | | `pinecone_db_index_fullness` | gauge | The greater of storage and memory fullness for a [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview) index, on a scale of 0 to 1. | | `pinecone_db_index_memory_fullness` | gauge | The memory used by a [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview) index as a ratio of its total memory capacity, on a scale of 0 to 1. | | `pinecone_db_index_storage_fullness` | gauge | The storage used by a [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview) index as a ratio of its total storage capacity, on a scale of 0 to 1. | ### Metric labels Each metric contains the following labels: | Label | Description | | :- | :- | | `index_name` | Name of the index to which the metric applies. | | `cloud` | Cloud where the index is deployed: `aws`, `gcp`, or `azure`. | | `region` | Region where the index is deployed. | | `capacity_mode` | Type of index: `serverless` or `byoc`. | | `instance` | Server instance (only available for counter metrics). | | `shard_id` | Shard identifier (only available for per-shard dedicated read node metrics). | ### Example queries Return the total number of records per index: ```shell theme={null} sum by (index_name) (pinecone_db_record_total) ``` Return the total number of records in Pinecone index `docs-example`: ```shell theme={null} pinecone_db_record_total{index_name="docs-example"} ``` For each index, return the total number of upsert requests per second: ```shell theme={null} sum by (index_name) (rate(pinecone_db_op_upsert_count[5m])) ``` Return the average processing time in milliseconds for upsert requests per index: ```shell theme={null} (sum by (index_name) (rate(pinecone_db_op_upsert_duration_sum[1m])))/(sum by (index_name) (rate(pinecone_db_op_upsert_count[1m]))) ``` For each index, return the total number of read units consumed per second: ```shell theme={null} sum by (index_name) (rate(pinecone_db_read_unit_count[5m])) ``` Return the total write units consumed per second for the Pinecone index `docs-example`: ```shell theme={null} sum (rate(pinecone_db_write_unit_count{index_name="docs-example"}[5m])) ``` Return the highest CPU usage percentage across all shards of Pinecone index `docs-example`: ```shell theme={null} max(pinecone_db_drn_cpu_usage_percent{index_name="docs-example"}) ``` For each dedicated read nodes index, return the highest CPU usage percentage across its shards: ```shell theme={null} max by (index_name) (pinecone_db_drn_cpu_usage_percent) ``` Return the fullness of Pinecone index `docs-example`: ```shell theme={null} pinecone_db_index_fullness{index_name="docs-example"} ``` Return the indexes that are at least 80% full: ```shell theme={null} pinecone_db_index_fullness >= 0.8 ``` # Production checklist Source: https://docs.pinecone.io/guides/production/production-checklist Prepare Pinecone indexes for production with best practices for project structure, security, scaling, API keys, and reliability across your workloads. This page provides recommendations and best practices for preparing your Pinecone indexes for production, anticipating production issues, and enabling reliability and growth. ## Prepare your project structure One of the first steps towards building a production-ready Pinecone index is configuring your project correctly. * Consider [creating a separate project](/admin/projects/create-a-project) for your development and production indexes, to allow for testing changes to your index before deploying them to production. * Ensure that you have properly [configured user access](/admin/projects/projects-overview#project-roles) to the Pinecone console, so that only those users who need to access the production index can do so. * Ensure that you have properly configured access through the API by [managing API keys](/admin/projects/manage-api-keys) and using API key permissions. Consider how best to [manage the API keys](/admin/projects/manage-api-keys) associated with your production project. To [make calls to the Pinecone API](/guides/get-started/quickstart), you must provide a valid API key for the relevant Pinecone project. ## Enforce security Use Pinecone's [security features](/admin/security/security-overview) to protect your production data: * Data security * Private endpoints * Customer-managed encryption keys (CMEK) for hosted projects; for BYOC, use KMS on your own resources ([Bring Your Own Cloud](/guides/production/bring-your-own-cloud)) * Authorization * API keys * Role-based access control (RBAC) * Organization single sign-on (SSO) * Audit logs * Bring Your Own Cloud ## Design your indexes for scale Follow these best practices when designing and populating your indexes: * **Data ingestion**: For large datasets (10M+ records), [import from object storage](/guides/data/import-data) for the most efficient and cost-effective ingestion. For ongoing ingestion, [upsert in batches](/guides/data/upsert-data#upsert-in-batches) to optimize speed and efficiency. See the [data ingestion overview](/guides/data/data-ingestion-overview) for details. * **Dimensionality**: Consider the dimensionality of your vectors. Higher dimensions can offer more accuracy but require more resources. * **Data modeling**: Use [structured IDs](/guides/indexes/data-modeling#use-structured-ids) (e.g., `document_id#chunk_number`) for efficient operations. Design [metadata](/guides/indexes/data-modeling#include-metadata) to support filtering, linking related chunks, and traceability. See the [data modeling guide](/guides/indexes/data-modeling) for details. * **Namespaces**: When indexing, try to [use namespaces to keep your data among tenants separate](/guides/data/implement-multitenancy), and don't use multiple indexes for this purpose. Namespaces are more efficient and more affordable in the long run. ## Understand database limits Architect your application to work within Pinecone's [database limits](/reference/api/database-limits): * **Rate limits**: Serverless indexes have per-second operation limits for queries, upserts, updates, and deletes. [Implement error handling with exponential backoff](/guides/production/error-handling) to handle rate limit errors gracefully. * **Size limits**: Be aware of constraints on vector dimensionality, metadata size per record, record ID length, maximum `top_k` values, and query result sizes. Design your [data model](/guides/indexes/data-modeling) accordingly. * **Index limits**: Plan for index capacity based on your [plan tier](https://www.pinecone.io/pricing/). Use [namespaces](/guides/data/implement-multitenancy) to partition data within indexes rather than creating multiple indexes. * **Plan limits**: The Starter and Builder plans have monthly read/write unit limits. Upgrade to Standard or Enterprise for unlimited read/write units and higher throughput needs. > [!NOTE] > > Indexes built on [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) aren't subject to read unit limits for query, fetch, list, and full-text search operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) guide. ## Test your query results Before you move your index to production, make sure that your index is returning accurate results in the context of your application by [identifying the appropriate metrics](https://www.pinecone.io/learn/offline-evaluation/) for evaluating your results. ## Optimize performance Before serving production workloads, optimize your Pinecone implementation: * **Increase search relevance**: Use techniques like reranking, metadata filtering, hybrid search, and chunking strategies to improve result quality. See [increase search relevance](/guides/optimize/increase-relevance) for details. * **Increase throughput**: Import from object storage, upsert in batches, use parallel operations, and use Python SDK optimizations like gRPC. See [increase throughput](/guides/optimize/increase-throughput) for details. * **Decrease latency**: Use namespaces, filter by metadata, target indexes by host, reuse connections, and deploy in the same cloud region as your index. See [decrease latency](/guides/optimize/decrease-latency) for details. * **Save on costs**: Prefer bulk import for large initial loads, use namespaces for multitenancy, and avoid unnecessary data in query responses. See [save on costs](/guides/cost/save-on-costs) for details. ## Backup up your indexes To enable long-term retention, compliance archiving, and deployment of new indexes, consider backing up your production indexes by [creating a backup or collection](/guides/indexes/back-up-an-index). ## Implement error handling Prepare your application to handle errors gracefully: * Implement [error handling and retry logic](/guides/production/error-handling) with exponential backoff * Handle different error types appropriately (4xx vs 5xx) * Monitor error rates and set up alerts * Check [status.pinecone.io](https://status.pinecone.io) before escalating issues ## Configure monitoring Prepare to [monitor the production performance and availability of your indexes](/guides/production/monitor-performance). ## Know how to get support If you need help, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket), or talk to the [Pinecone community](https://www.pinecone.io/community/). Ensure that your [plan tier](https://www.pinecone.io/pricing/) matches the support and availability SLAs you need. This may require you to upgrade to Enterprise. # Bring your own vectors Source: https://docs.pinecone.io/guides/search/bring-your-own-vectors Store embeddings you generate yourself in a document index, then search them by vector similarity with a query vector from the same model. If you already generate embeddings, store them in a `dense_vector` field on a document index. This fits when you use a model Pinecone doesn't host, a model you've fine-tuned, or vectors you've already computed. You embed every document before you upsert it and every query before you search. To have Pinecone embed your text instead, use [integrated embedding](/guides/search/integrated-embedding). For a legacy vector index, see [Create a vector index](/guides/legacy/vectors-api/create-a-vector-index), [Upsert vectors](/guides/legacy/vectors-api/upsert-vectors), and [Query vectors](/guides/legacy/vectors-api/query-vectors). The steps use an SDK or the REST API, with your API key in the `PINECONE_API_KEY` environment variable. To set them up, see the [quickstart](/guides/get-started/quickstart#set-it-up-yourself). The JavaScript examples use top-level `await`, so run them as an ES module. The Go examples build one `main` function: the first block is the full program, and each later block adds to it. ### 1. Generate embeddings for your documents Embed each document's text with the model of your choice. So the example runs as is, it uses Pinecone's hosted `llama-text-embed-v2` model through the [standalone embedding API](/reference/api/latest/inference/generate-vectors), which returns 1,024-dimension vectors. Set `input_type` to `passage` for documents. ```python Python theme={null} import os, time from pinecone import Pinecone, SchemaBuilder pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) texts = [ "Refund requests must be submitted within 30 days of purchase.", "Enterprise customers get support with a 4-hour response time.", "Error E1042: the connection timed out after 30 seconds. Retry with a longer timeout.", "To reset your password, open Settings and choose Security.", "Order 88231 shipped on 2026-08-20 via express courier.", ] embeddings = pc.inference.embed( model="llama-text-embed-v2", inputs=texts, parameters={"input_type": "passage"}, ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone(); // reads PINECONE_API_KEY const texts = [ 'Refund requests must be submitted within 30 days of purchase.', 'Enterprise customers get support with a 4-hour response time.', 'Error E1042: the connection timed out after 30 seconds. Retry with a longer timeout.', 'To reset your password, open Settings and choose Security.', 'Order 88231 shipped on 2026-08-20 via express courier.', ]; const embeddings = await pc.inference.embed({ model: 'llama-text-embed-v2', inputs: texts, parameters: { inputType: 'passage' }, }); ``` ```go Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{}) // reads PINECONE_API_KEY if err != nil { log.Fatal(err) } texts := []string{ "Refund requests must be submitted within 30 days of purchase.", "Enterprise customers get support with a 4-hour response time.", "Error E1042: the connection timed out after 30 seconds. Retry with a longer timeout.", "To reset your password, open Settings and choose Security.", "Order 88231 shipped on 2026-08-20 via express courier.", } embeddings, err := pc.Inference.Embed(ctx, &pinecone.EmbedRequest{ Model: "llama-text-embed-v2", TextInputs: texts, Parameters: pinecone.EmbedParameters{"input_type": "passage"}, }) if err != nil { log.Fatal(err) } } ``` ```bash curl theme={null} TEXTS='[ "Refund requests must be submitted within 30 days of purchase.", "Enterprise customers get support with a 4-hour response time.", "Error E1042: the connection timed out after 30 seconds. Retry with a longer timeout.", "To reset your password, open Settings and choose Security.", "Order 88231 shipped on 2026-08-20 via express courier." ]' # Embed the texts and save the response (requires jq) jq -n --argjson t "$TEXTS" \ '{model: "llama-text-embed-v2", parameters: {input_type: "passage"}, inputs: [$t[] | {text: .}]}' | curl -s -X POST "https://api.pinecone.io/embed" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d @- > embeddings.json ``` ### 2. Create an index with a dense_vector field Declare a `dense_vector` field whose `dimension` matches your model's output and whose `metric` matches what the model was trained for. `llama-text-embed-v2` uses `cosine`. This schema also declares `chunk_text` with `full_text_search`, so the index stores each document's text and can rank it by keyword too. Fields you don't declare are stored as metadata. ```python Python theme={null} schema = ( SchemaBuilder() .add_dense_vector_field("embedding", dimension=1024, metric="cosine") .add_string_field("chunk_text", full_text_search={"language": "en"}) .build() ) if not pc.indexes.exists(name="byo-vectors"): pc.indexes.create(name="byo-vectors", schema=schema) while not pc.indexes.describe(name="byo-vectors").status.ready: time.sleep(2) index = pc.index(name="byo-vectors") ``` ```javascript JavaScript theme={null} await pc.indexes.create({ name: 'byo-vectors', schema: { fields: { embedding: { type: 'dense_vector', dimension: 1024, metric: 'cosine' }, chunk_text: { type: 'string', fullTextSearch: { language: 'en' } }, }, }, waitUntilReady: true, suppressConflicts: true, }); const index = pc.index({ name: 'byo-vectors', namespace: '__default__' }); ``` ```go Go theme={null} // Add "time" to your imports, then add to the main function: if _, err := pc.DescribeIndex(ctx, "byo-vectors"); err != nil { language := "en" _, err = pc.CreateIndex(ctx, &pinecone.CreateIndexRequest{ Name: "byo-vectors", Schema: pinecone.IndexSchema{ Fields: map[string]pinecone.IndexSchemaField{ "embedding": {DenseVector: &pinecone.DenseVectorField{ Dimension: 1024, Metric: pinecone.IndexMetricCosine, }}, "chunk_text": {String: &pinecone.StringField{ FullTextSearch: &pinecone.FullTextSearchConfig{Language: &language}, }}, }, }, }) if err != nil { log.Fatal(err) } } idx, err := pc.DescribeIndex(ctx, "byo-vectors") for err == nil && !idx.Status.Ready { time.Sleep(2 * time.Second) idx, err = pc.DescribeIndex(ctx, "byo-vectors") } if err != nil { log.Fatal(err) } index, err := pc.Index(pinecone.NewIndexConnParams{Host: idx.Host, Namespace: "__default__"}) if err != nil { log.Fatal(err) } ``` ```bash curl theme={null} curl -X POST "https://api.pinecone.io/indexes" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "name": "byo-vectors", "schema": { "fields": { "embedding": { "type": "dense_vector", "dimension": 1024, "metric": "cosine" }, "chunk_text": { "type": "string", "full_text_search": { "language": "en" } } } } }' # Wait until the index is ready, then save its host until curl -s "https://api.pinecone.io/indexes/byo-vectors" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" | jq -e '.status.ready' > /dev/null; do sleep 2 done INDEX_HOST=$(curl -s "https://api.pinecone.io/indexes/byo-vectors" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" | jq -r '.host') ``` ### 3. Upsert documents with their vectors Put each vector on the `embedding` field, next to the text it came from. Each vector must have exactly 1,024 values. Documents are indexed asynchronously, so the code waits 10 seconds before you search. ```python Python theme={null} index.documents.upsert( namespace="__default__", documents=[ {"_id": str(i + 1), "chunk_text": text, "embedding": e.values} for i, (text, e) in enumerate(zip(texts, embeddings)) ], ) time.sleep(10) # documents are indexed asynchronously, so wait a moment ``` ```javascript JavaScript theme={null} await index.documents.upsert({ documents: texts.map((text, i) => ({ _id: String(i + 1), chunk_text: text, embedding: embeddings.data[i].values, })), }); await new Promise((resolve) => setTimeout(resolve, 10000)); // documents are indexed asynchronously, so wait a moment ``` ```go Go theme={null} // Add "strconv" to your imports, then add to the main function: var documents []pinecone.Document for i, text := range texts { documents = append(documents, pinecone.Document{ "_id": strconv.Itoa(i + 1), "chunk_text": text, "embedding": embeddings.Data[i].DenseEmbedding.Values, }) } if _, err := index.UpsertDocuments(ctx, &pinecone.UpsertDocumentsRequest{Documents: documents}); err != nil { log.Fatal(err) } time.Sleep(10 * time.Second) // documents are indexed asynchronously, so wait a moment ``` ```bash curl theme={null} jq -n --argjson t "$TEXTS" --slurpfile e embeddings.json \ '{documents: [range(0; $t | length) as $i | {_id: ($i + 1 | tostring), chunk_text: $t[$i], embedding: $e[0].data[$i].values}]}' | curl -X POST "https://$INDEX_HOST/namespaces/__default__/documents/upsert" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d @- sleep 10 # documents are indexed asynchronously, so wait a moment ``` ### 4. Embed your query Embed the query with the same model you used for the documents. Vectors from different models aren't comparable, so a different model returns meaningless rankings. For `llama-text-embed-v2`, set `input_type` to `query`. ```python Python theme={null} query = pc.inference.embed( model="llama-text-embed-v2", inputs=["how do I get my money back?"], parameters={"input_type": "query"}, ) ``` ```javascript JavaScript theme={null} const query = await pc.inference.embed({ model: 'llama-text-embed-v2', inputs: ['how do I get my money back?'], parameters: { inputType: 'query' }, }); ``` ```go Go theme={null} // Add to the main function: query, err := pc.Inference.Embed(ctx, &pinecone.EmbedRequest{ Model: "llama-text-embed-v2", TextInputs: []string{"how do I get my money back?"}, Parameters: pinecone.EmbedParameters{"input_type": "query"}, }) if err != nil { log.Fatal(err) } ``` ```bash curl theme={null} curl -s -X POST "https://api.pinecone.io/embed" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "model": "llama-text-embed-v2", "parameters": { "input_type": "query" }, "inputs": [{ "text": "how do I get my money back?" }] }' | jq '.data[0].values' > query.json ``` ### 5. Search by vector similarity Score by `dense_vector` and pass the query vector in `values`. Pinecone ranks documents by the field's `metric`. ```python Python theme={null} results = index.documents.search( namespace="__default__", top_k=3, score_by=[{"type": "dense_vector", "fields": ["embedding"], "values": query.data[0].values}], include_fields=["chunk_text"], ) for m in results.matches: print(m.id, f"{m.score:.3f}", m.chunk_text) ``` ```javascript JavaScript theme={null} const results = await index.documents.search({ topK: 3, scoreBy: [{ type: 'dense_vector', fields: ['embedding'], values: query.data[0].values }], includeFields: ['chunk_text'], }); for (const m of results.matches) { console.log(m._id, m._score.toFixed(3), m.chunk_text); } ``` ```go Go theme={null} // Add "fmt" to your imports, then add to the main function: queryVector := query.Data[0].DenseEmbedding.Values results, err := index.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{ TopK: 3, ScoreBy: []pinecone.DocumentScoringMethod{ {Type: pinecone.DocumentScoringTypeDenseVector, Fields: []string{"embedding"}, Values: &queryVector}, }, IncludeFields: []string{"chunk_text"}, }) if err != nil { log.Fatal(err) } for _, m := range results.Matches { fmt.Printf("%s %.3f %s\n", m.Id, *m.Score, m.Fields["chunk_text"]) } ``` ```bash curl theme={null} jq -n --slurpfile q query.json \ '{top_k: 3, score_by: [{type: "dense_vector", fields: ["embedding"], values: $q[0]}], include_fields: ["chunk_text"]}' | curl -X POST "https://$INDEX_HOST/namespaces/__default__/documents/search" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d @- ``` The refund policy ranks first: ```text Output theme={null} 1 0.417 Refund requests must be submitted within 30 days of purchase. 4 0.119 To reset your password, open Settings and choose Security. 2 0.089 Enterprise customers get support with a 4-hour response time. ``` Because `chunk_text` declares `full_text_search`, the same index also supports a [full-text search](/guides/search/full-text-search) on the text, and either search accepts a [metadata filter](/guides/search/filter-by-metadata). # Filter by metadata Source: https://docs.pinecone.io/guides/search/filter-by-metadata Narrow Pinecone search results with metadata filter expressions such as $eq, $in, $gt, and $and, and with text-match filters on document indexes. [Documents](/guides/get-started/key-terms#document) can carry [metadata](/guides/indexes/index-data-overview#metadata), key-value pairs that store related information. When you search, add a metadata filter to limit results to the documents that match it. Document indexes also support [text-match filters](#text-match-filters) on full-text fields. For a legacy vector index, see [Query with a metadata filter](/guides/legacy/vectors-api/query-vectors#query-with-a-metadata-filter). For a legacy integrated index, see [Search with a metadata filter](/guides/legacy/records-api/search-with-text#search-with-a-metadata-filter). ## Search with a metadata filter The following code searches for the 3 documents that are most semantically similar to a query and that have a `category` metadata field with the value `digestive system`. On a document index with [integrated embedding](/guides/search/integrated-embedding), you search with query text, and Pinecone embeds it with the model declared on the field. This example assumes a `chunk_text` field declared with `embed`. ```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/indexes/target-an-index index = pc.index(host="INDEX_HOST") filtered_results = index.documents.search( namespace="example-namespace", top_k=3, score_by=[ {"type": "embed", "fields": ["chunk_text"], "query": "Disease prevention"} ], filter={"category": {"$eq": "digestive system"}}, include_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/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST', namespace: 'example-namespace' }); const response = await index.documents.search({ topK: 3, scoreBy: [ { type: 'embed', fields: ['chunk_text'], query: 'Disease prevention' }, ], filter: { category: { $eq: 'digestive system' } }, includeFields: ['category', 'chunk_text'], }); console.log(response); ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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/indexes/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) } query := "Disease prevention" res, err := idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{ TopK: 3, ScoreBy: []pinecone.DocumentScoringMethod{ {Type: pinecone.DocumentScoringTypeEmbed, Fields: []string{"chunk_text"}, Query: &query}, }, Filter: map[string]interface{}{ "category": map[string]interface{}{"$eq": "digestive system"}, }, IncludeFields: []string{"category", "chunk_text"}, }) if err != nil { log.Fatalf("Failed to search documents: %v", err) } fmt.Println(prettifyStruct(res)) } ``` ```bash curl theme={null} INDEX_HOST="INDEX_HOST" NAMESPACE="example-namespace" PINECONE_API_KEY="YOUR_API_KEY" curl "https://$INDEX_HOST/namespaces/$NAMESPACE/documents/search" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "top_k": 3, "score_by": [ { "type": "embed", "fields": ["chunk_text"], "query": "Disease prevention" } ], "filter": { "category": { "$eq": "digestive system" } }, "include_fields": ["category", "chunk_text"] }' ``` ## Metadata filter expressions Pinecone's filtering language supports the following operators: | Operator | Function | Supported types | | :- | :- | :- | | `$eq` | Matches records or documents with metadata values that are equal to a specified value. Example: `{"genre": {"$eq": "documentary"}}` | Number, string, boolean | | `$ne` | Matches records or documents with metadata values that aren't equal to a specified value. Example: `{"genre": {"$ne": "drama"}}` | Number, string, boolean | | `$gt` | Matches records or documents with metadata values that are greater than a specified value. Example: `{"year": {"$gt": 2019}}` | Number | | `$gte` | Matches records or documents with metadata values that are greater than or equal to a specified value. Example:`{"year": {"$gte": 2020}}` | Number | | `$lt` | Matches records or documents with metadata values that are less than a specified value. Example: `{"year": {"$lt": 2020}}` | Number | | `$lte` | Matches records or documents with metadata values that are less than or equal to a specified value. Example: `{"year": {"$lte": 2020}}` | Number | | `$in` | Matches records or documents with metadata values that are in a specified array. The array can hold up to [10,000 values](/reference/api/database-limits/operation-limits#metadata-filter-limits). Example: `{"genre": {"$in": ["comedy", "documentary"]}}` | String, number | | `$nin` | Matches records or documents with metadata values that aren't in a specified array. The array can hold up to [10,000 values](/reference/api/database-limits/operation-limits#metadata-filter-limits). Example: `{"genre": {"$nin": ["comedy", "documentary"]}}` | String, number | | `$exists` | Matches records or documents 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}}]}` | - | | `$not` | Matches records or documents that don't match the wrapped clause. Example: `{"genre": {"$not": {"$eq": "drama"}}}` | - | At the top level, list one or more fields (combined with implicit AND) or combine clauses with the logical operators `$and` and `$or`. Use `$not` to negate a clause, as shown in the table. A bare comparison operator (like `$gt`) can't appear at the top level. Nest it under a field. A metadata field can hold an array of strings, such as `{"genre": ["comedy", "documentary"]}`. A filter on that field matches when any value in the array satisfies it, so each of these filters matches: ```json JSON theme={null} {"genre": "comedy"} {"genre": {"$in": ["documentary", "action"]}} {"$and": [{"genre": "comedy"}, {"genre": "documentary"}]} ``` These filters don't match, because the array has no `"drama"` value and because `$ne` and `$nin` exclude an item when any of its values matches: ```json JSON theme={null} {"$and": [{"genre": "comedy"}, {"genre": "drama"}]} {"genre": {"$ne": "comedy"}} ``` A filter value can't be an array. To match several values, use `$in`. These filters are invalid and return a `400` error: ```json JSON theme={null} {"genre": ["comedy", "documentary"]} {"genre": {"$eq": ["comedy", "documentary"]}} ``` ## Text-match filters On a [document index](/guides/indexes/data-modeling#documents), three more operators match text in `string` fields that have `full_text_search` enabled, or that declare `embed` or `sparse_embed` without setting `store_text: false`. Like metadata operators, they narrow the candidates before scoring. | Operator | Example | Description | | - | - | - | | `$match_phrase` | `{"body": {"$match_phrase": "machine learning"}}` | Exact phrase match (contiguous tokens) on a text-searchable field. | | `$match_all` | `{"body": {"$match_all": "machine learning"}}` | All tokens present, in any order. | | `$match_any` | `{"body": {"$match_any": "AI robotics"}}` | At least one token present. | Text-match operators use the field's tokenizer and stemmer, so a token that matches in BM25 scoring also matches in a filter. Filter values are literal text. Lucene syntax such as phrase slop (`"phrase"~N`), term boosting (`^N`), and phrase prefix (`"phrase pre"*`) isn't parsed. To use it, score with `query_string` instead. You can combine text-match operators 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 } } ] } ``` > [!WARNING] > > Text-match operators work on `documents/search` and [`documents/fetch`](/guides/data/fetch-data#fetch-documents). A filtered [`documents/update`](/guides/data/update-data#update-documents) or [`documents/delete`](/guides/data/delete-data#delete-documents) rejects them with a `400`. To update or delete by text match, first search or fetch to get the matching IDs, then update or delete by ID. # Full-text search overview 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 ranks documents by keyword and phrase relevance using **BM25** scoring, with optional **Lucene** query syntax. Because a document index 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 meaning-based retrieval, use [semantic search](/guides/search/semantic-search) on the same document index. See [Search overview](/guides/search/search-overview) to choose the right approach. > [!NOTE] > > Full-text search requires [API version](/reference/api/versioning) `2026-07`. Send `X-Pinecone-Api-Version: 2026-07` on REST requests, or use a `2026-07` SDK (Python v10 or later, Node.js v9 or later, or Go v7 or later). ## Capabilities What full-text search does and doesn't match: | Capability | Status | | - | - | | Fuzzy matching (typo tolerance) | Supported in `query_string` queries only ([query syntax](/guides/search/full-text-search/query-syntax)) | | Stemming | Supported, opt-in per field at index creation ([stemming](/guides/search/full-text-search/text-processing#stemming)) | | Stop-word removal | Supported, opt-in per field at index creation ([tokens & analyzers](/guides/search/full-text-search/text-processing#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](/guides/search/full-text-search/text-processing#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. | ## How it works Pinecone's [Documents API](/guides/get-started/documents-api) stores typed fields you declare in a schema. End to end, the flow is short: 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. ### Interfaces You can do each step (creating the index, upserting documents, and searching) with the REST API, a Pinecone SDK (Python, Node.js, or Go), or the Pinecone console. This page uses the API and SDK; the console covers the same operations with a UI. ### Documents and schemas Creating and populating an index takes three steps: 1. Create an index with a schema that declares your ranking fields and how each is indexed. You declare only ranking fields, not metadata fields. For the field types you can declare, see [Schema field types](#schema-field-types). 2. Upsert your data as JSON documents, each with a required `_id`. 3. Pinecone indexes each declared field by its type. Any other field on an upserted document is automatically stored and indexed for filtering, with no schema declaration. Filterable metadata isn't part of the schema. Any field you upsert that's not declared in the schema is stored on the document, returned via `include_fields`, and automatically indexed for filtering. See [Metadata fields](#metadata-fields). Newly upserted documents are indexed asynchronously, so they may not be searchable immediately. To confirm that an index holds the documents you expect, see [Check data freshness](/guides/data/check-data-freshness). ### Scoring Every search ranks by one scoring type. The `score_by` clause selects the scoring method for the request: * `text`, BM25 token matching over one or more FTS-enabled `string` fields. * `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. * `embed`, dense similarity against a `string` field with `embed`, where Pinecone embeds your query text with the field's model. * `sparse_embed`, learned-sparse similarity against a `string` field with `sparse_embed`, where Pinecone embeds your query text with the field's model. The same index can support all of these when the schema declares the corresponding fields, but a given request commits to one scoring type. 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, and the `score_by` ranks what remains. This is the most common hybrid pattern. The alternative is to run separate searches and merge the results client-side, for example with [reciprocal rank fusion](/guides/search/reciprocal-rank-fusion). 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", "fields": ["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. BM25 can also rank on several fields at once. Name multiple fields in one `text` clause, or pass multiple `text` clauses, and Pinecone combines them into a single ranking. A `query_string` clause can target several fields too. Every field contributes equally in `2026-07`, and there's no per-field weight parameter. ## End-to-end example A complete run from index creation through search. Copy this into a single file, set `PINECONE_API_KEY`, and run. > [!TIP] > > For a runnable version, see this [Google Colab notebook](https://colab.research.google.com/drive/1lsPeNLCJ2ucbYthHYs9WpybW4nAfB8tG), which upserts and searches a sample Wikipedia dataset. ```python Python theme={null} import os import time from pinecone import Pinecone, 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.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.indexes.describe(name="articles-quickstart").status.ready: time.sleep(2) index = pc.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", "fields": ["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. A `string` field that declares none of `full_text_search`, `embed`, or `sparse_embed` is rejected at index creation, since 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. For large datasets, use [Import](/guides/data/import-data) instead. * **`score_by=[{"type": "text", ...}]`** picks BM25 as the scoring type. One scoring type per request; combine scoring with text matching via `filter` rather than mixing scoring 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. ## 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. ## Schema definition The schema is required at [index creation](/guides/indexes/create-an-index) and declares the fields that drive ranking or vector search. Filterable metadata isn't declared in the schema: any field you upsert that isn't in the schema is automatically stored and indexed for filtering. A schema can declare up to 100 `string` fields with `full_text_search` enabled. An index has one dense slot and one sparse slot: at most one dense field (a `dense_vector` field, or a `string` field with `embed`) and at most one sparse field (a `sparse_vector` field, or a `string` field with `sparse_embed`). ### 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 | None | | `string` (text) | Full-text search and/or server-side embedding. Set `full_text_search` for BM25, `embed` for dense embedding, `sparse_embed` for learned-sparse embedding; combine them on one field. See [Integrated embedding](/guides/search/integrated-embedding). | `full_text_search` (`language`, `stemming`, `stop_words`, `ngram`), `embed` (`model`, `dimension`, `metric`, `write_parameters`, `read_parameters`), `sparse_embed` (`model`, `write_parameters`, `read_parameters`), and `store_text`, all optional | > [!NOTE] > > Schemas can only declare ranking fields, so declaring a metadata-only field is rejected at index creation with a `400` error. A field is metadata-only when it's a `string_list`, `float`, or `boolean` field, or a `string` field that sets none of `full_text_search`, `embed`, or `sparse_embed`. Metadata fields are auto-indexed at upsert time. See [Metadata fields](#metadata-fields). 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, and match scores are returned as `_score` to avoid collisions. > [!NOTE] > > To rank by vector similarity, either supply your own vectors through a `dense_vector` or `sparse_vector` field, or have Pinecone embed a `string` field's text for you with `embed` or `sparse_embed`. Both compose with `full_text_search` on the same index. See [Integrated embedding](/guides/search/integrated-embedding). The `semantic_text` type isn't declared directly; it appears only when you describe an index created with the legacy [Create an index with integrated embedding](/reference/api/2026-07/control-plane/create_for_model) operation. > [!NOTE] > > A `string` field with `full_text_search` isn't metadata and doesn't count toward the 40 KB metadata limit for documents. Use these FTS-enabled `string` fields for searchable chunk text. ### Example schemas A text-only schema. The minimal `{}` config 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 } } } } } ``` > [!NOTE] > > Including `full_text_search`, even an empty object `{}`, turns full-text search on for a `string` field. A `string` field must declare `full_text_search`, `embed`, or `sparse_embed`; one with none of these is rejected at index creation, because schemas only declare ranking fields. A multi-field schema with text, dense, and sparse vectors: ```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 don't 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's not declared in the schema is treated as metadata: it's 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. Because metadata isn't declared anywhere, track the field names and types you use in your application. > [!NOTE] > > You can't add, remove, or modify a document index's fields after you create it. To give an existing legacy vector index or legacy integrated index a schema, [convert it](/guides/indexes/convert-an-index). ## Schema validation Documents are validated against the index schema on upsert. If any document is invalid, the entire upsert fails and nothing is written. For the validation rules, see [Schema validation](/guides/indexes/data-modeling#schema-validation). ## Filter operators Filters are applied *before* the search runs, so the search only considers documents that match. On document indexes, a filter can use the comparison and set operators (`$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$exists`), the logical operators `$and`, `$or`, and `$not`, and the [text-match operators](/guides/search/filter-by-metadata#text-match-filters) (`$match_phrase`, `$match_all`, `$match_any`) on FTS-enabled `string` fields. Multiple fields at the top level of a `filter` object combine with implicit AND. For operator details and examples, see [Filter by metadata](/guides/search/filter-by-metadata). ## Search examples These examples combine `score_by` scoring with `filter` narrowing on a document index. ### Token matching with a 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-07" \ -d '{ "include_fields": ["title", "body", "category", "year"], "filter": { "category": { "$eq": "technology" }, "year": { "$gte": 2024 } }, "score_by": [{ "type": "text", "fields": ["body"], "query": "machine learning" }], "top_k": 10 }' ``` ### Cross-field boolean query (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-07" \ -d '{ "include_fields": ["title", "body"], "score_by": [{ "type": "query_string", "query": "title:(quantum) OR body:(machine learning)" }], "top_k": 10 }' ``` ### Dense 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-07" \ -d '{ "include_fields": ["title", "body"], "filter": { "body": { "$match_phrase": "machine learning" } }, "score_by": [{ "type": "dense_vector", "fields": ["embedding"], "values": [0.12, 0.34, 0.56] }], "top_k": 10 }' ``` ### BM25 ranking with a text-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-07" \ -d '{ "include_fields": ["body", "category", "year"], "filter": { "$and": [ { "body": { "$match_all": "federal reserve" } }, { "category": { "$eq": "finance" } } ] }, "score_by": [{ "type": "text", "fields": ["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-07" \ -d '{ "include_fields": ["body", "category"], "filter": { "$and": [ { "body": { "$match_phrase": "large language model" } }, { "body": { "$not": { "$match_any": "spam advertisement" } } } ] }, "score_by": [{ "type": "text", "fields": ["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". For the full request and response schema, see [Search documents](/reference/api/latest/data-plane/search_documents). ## Troubleshooting > [accordion] Document not appearing in search results > > * 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. > [accordion] Unexpected search 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're treated as literal words. > [accordion] Query syntax errors > > 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. > [accordion] API errors > > * `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 `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-07`. > [accordion] Upsert errors > > * Type mismatch: Ensure values match declared schema types. > * Invalid `_id`: Every document must have a non-empty `_id` string. > * Reserved names: Field names can't start with `_` (reserved for system-managed fields like `_id` and `_score`) or `$` (reserved for filter operators), and must be at most 64 bytes. > [accordion] Slow search performance > > * 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. > [accordion] Common request-shape pitfalls > > 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. ## Requirements and limitations These requirements and limitations apply to document indexes. For dense and sparse vector indexes, and for legacy integrated indexes (created with create-index-for-model on the legacy Records API), see [Search overview](/guides/search/search-overview). ### Requirements * **Entry points**: Use the REST API, a `2026-07` SDK (Python v10 or later, Node.js v9 or later, or Go v7 or later), or the Pinecone console. REST requests must send `X-Pinecone-Api-Version: 2026-07`, and the SDKs send it for you. * **Endpoint compatibility**: Document indexes use the `/namespaces/{namespace}/documents/*` endpoints, including when a `string` field embeds its text with `embed` or `sparse_embed`. Dense and sparse vector indexes use `/vectors/*`, and legacy integrated indexes (create-index-for-model) use `/records/*`. The endpoint families are index-type-specific and don't cross over. * **Deployment**: Supported on managed (serverless) and [BYOC](/guides/production/bring-your-own-cloud) deployments, with `read_capacity.mode` set to `OnDemand` or `Dedicated`. ### Limits * **Document and schema limits**: See [Upsert limits](/reference/api/database-limits/operation-limits#upsert-limits) for fields per schema, field and token size, document size, request size, and metadata size. * **Query limits**: See [Query limits](/reference/api/database-limits/operation-limits#query-limits) for the `top_k` and result-size caps. Full-text search is optimized for ranked retrieval rather than for aggregation or count-style queries. * **Update limits**: See [Update limits](/reference/api/database-limits/operation-limits#update-limits) for how many documents one update request can patch. ### Supported operations * **Partial updates**: Upsert replaces the whole document for a given `_id`. `POST /namespaces/{namespace}/documents/update` patches individual fields, by ID or by metadata filter. See [Update documents](/guides/data/update-data#update-documents). * **Bulk import** from object storage, via JSONL files, except into an index with an `embed` or `sparse_embed` field. See [Prepare document-schema files (JSONL)](/guides/data/import-data#prepare-document-schema-files-jsonl). * **Namespace operations**: You can [create, list, describe, and delete namespaces](/guides/data/manage-namespaces) on a document index, and [describing a namespace](/guides/data/manage-namespaces#describe-a-namespace) returns its `record_count` and `size_bytes`. * **`describe_index_stats`**: In the REST response, `totalVectorCount` and each namespace's `vectorCount` count documents, and both are accurate for every schema. `dimension` and `metric` describe the schema's dense field (a `dense_vector` field, or a `string` field with `embed`), and `vectorType` is `dense`. When a schema declares no dense field, `metric` falls back to `dotproduct`, and `dimension` is `0` on a text-only schema (`vectorType` is `text`) or is omitted when the schema declares a sparse field (a `sparse_vector` field, or a `string` field with `sparse_embed`) and `vectorType` is `sparse`. For the full response schema, see [Get index stats](/reference/api/latest/data-plane/describeindexstats). ### Not supported * You can't change a document index's schema after creating it. To give a legacy vector index or legacy integrated index a schema, [convert it](/guides/indexes/convert-an-index) into a new document index. * Indexes can't be created in projects with [customer-managed encryption keys (CMEK)](/guides/production/configure-cmek) enabled. * An index can't be changed from dedicated read capacity back to on-demand. Create a new on-demand index and reingest your data. ## Pricing Reads and writes on document indexes are metered using the same [read units (RUs)](/guides/cost/understand-cost#read-units) and [write units (WUs)](/guides/cost/understand-cost#write-units) model as legacy vector indexes. A schema that declares `embed` or `sparse_embed` also bills for [embedding](/guides/cost/understand-cost#embedding) by the token, on top of RUs and WUs. Writes re-embed on every request, so a retried or duplicate write is embedded and metered again. # Full-text search query syntax Source: https://docs.pinecone.io/guides/search/full-text-search/query-syntax Write Pinecone full-text search queries with Lucene query_string syntax, including boolean, phrase, prefix, boosting, and fuzzy operators. Full-text search offers two text-based query types: `type: "text"` for BM25 token search over one or more named fields, and `type: "query_string"` for the full Lucene grammar, with boolean operators, phrases, boosting, fuzzy matching, and more. ## Choosing a query type The two types differ in the capabilities they support: | Feature | `type: "text"` | `type: "query_string"` | | - | - | - | | **Purpose** | Token search on one or more fields | Lucene query syntax | | **Field targeting** | Required `fields`, one or more text fields (scores against all) | No `field`/`fields` param; use Lucene field qualifiers (`title:(...)`) in the query | | **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) | | **Single-term prefix** (`auto*`) | Not supported | Not supported. Use [phrase prefix](#phrase-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](/guides/search/full-text-search/text-processing#stemming)) | Supported ([when enabled](/guides/search/full-text-search/text-processing#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](/guides/search/full-text-search/text-processing#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 | Doesn't 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 the clause's relevance score by N (`0` or greater, decimals allowed) | | 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 | ### Terms and default OR behavior 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. ### Phrases 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's 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](/guides/search/full-text-search/text-processing#stemming) is enabled on the field, the phrase terms stem too, e.g., `"running fast"` matches `running fast` and `runs fast`.* ### Boolean operators (AND, OR, NOT) 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" ``` AND binds tighter than OR, so use parentheses to control order: ``` body:((database OR storage) AND distributed) ``` ### Required and excluded terms (+, -) 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" ``` ### Phrase proximity (slop) 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](/guides/search/full-text-search/text-processing#stemming) (when enabled on the field) applies here too.* ### Boosting Use `^N` to multiply a clause's contribution to the relevance score, where `N` is `0` or greater. The default is `1`, so `^2` doubles the contribution and `^0.5` halves it. Scaling is linear. ``` body:(machine^3 learning) # "machine" weighted 3x more than "learning" body:(machine^0.5 learning) # "machine" weighted half as much as "learning" body:("neural network"^2 deep) # Phrase boosted 2x body:((machine OR neural)^2 deep) # Whole group boosted 2x ``` Attach `^N` directly to a term, a quoted phrase, or a parenthesized group. A space on either side of `^`, as in `body:(machine ^2 learning)`, is a query error (`400`). * **`N` is a literal number**, whole or decimal, with digits on both sides of the decimal point, such as `2`, `1.5`, or `0.75`. * **Values below `1`** reduce the clause's weight, and `^1` leaves scoring unchanged. * **`^0`** drops the clause's contribution to zero, though documents matching it are still returned. If every clause in the query is boosted to `0`, all matches score `0` and their order isn't meaningful. * **Anything else is a query error (`400`)**: Arithmetic (`^(2*3)`), negatives (`^-2`), scientific notation (`^1e3`), a bare leading decimal point (`^.5`), and chained boosts (`^2^3`). There's no function- or field-based scoring, so weight by a stored field value or a formula in your application after the search returns. Boosting is available only with `type: "query_string"`. With `type: "text"` and in the [text-match filters](/guides/search/filter-by-metadata#text-match-filters), `^` is treated as a literal character. ### Phrase prefix 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" ``` A single-term prefix wildcard, such as `auto*`, isn't supported. It returns no matches rather than an error. Use a phrase prefix instead, or configure the field for [substring search](/guides/search/full-text-search/text-processing#substring-search-with-n-grams). Both the literal terms and the prefix are matched against the field's analyzed tokens. If [stemming](/guides/search/full-text-search/text-processing#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` isn't among the first 50 expanded terms for `yo`. ### Regex 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's not supported with `type: "text"`. ### Fuzzy matching (typo tolerance) 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. > [!NOTE] > > The `~` operator is fuzzy only when it follows a **bare term**. After a quoted phrase, `~N` keeps its [phrase slop](#phrase-proximity-slop) meaning, for example, `body:("machine learning"~2)` is slop, while `body:(learning~2)` is fuzzy. There is no fuzzy phrase matching. > [!NOTE] > > On [stemmed](/guides/search/full-text-search/text-processing#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. Fuzzy also doesn't apply in the `$match_phrase`, `$match_all`, and `$match_any` [text-match filters](/guides/search/filter-by-metadata#text-match-filters), where a `~` operator is matched literally and the filter finds nothing. ### Cross-field queries `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. # Full-text search text processing Source: https://docs.pinecone.io/guides/search/full-text-search/text-processing Control how Pinecone full-text search tokenizes and analyzes text, including tokens and analyzers, stemming, language options, and substring (n-gram) matching. Configure how Pinecone indexes and matches text in your full-text-search fields. These options are set per field at index creation. ## 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`](/guides/search/filter-by-metadata#text-match-filters)) 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 can't 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. 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. A single token can be up to 1,024 bytes, measured after splitting and before lowercasing or stemming. Tokens aren't truncated: an upsert, `text` query, or `query_string` query that contains a longer token fails with a `400` error, and a `$match_*` filter ignores a longer token without an error. This limit is server-applied and can't be overridden. 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. These fields accept tokens over 1,024 bytes at upsert, but a query token over 1,024 bytes still fails with a `400` error. ### 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 don't 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 aren't interchangeable with FTS analyzer tokens, and `$match_*` filters don't 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. ## 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. Stemming applies to both `type: "text"` and `type: "query_string"` queries on the field. > [!NOTE] > > Stemming is set at index creation and can't be changed afterward. ### Enable stemming with French ```json theme={null} { "schema": { "fields": { "body": { "type": "string", "full_text_search": { "stemming": true, "language": "french" } } } } } ``` ## 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"`). > [!NOTE] > > Language is set at index creation and can't be changed afterward. ### 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 | ## Substring search with n-grams By default, full-text search matches whole tokens: a query for `comp` doesn't 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 needs no special syntax. 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", "fields": ["product_name"], "query": "sear", } ], include_fields=["product_name"], ) ``` > [!NOTE] > > N-gram tokenization can't 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. > [!NOTE] > > N-gram configuration is set at index creation and can't be changed afterward. # Hybrid search overview Source: https://docs.pinecone.io/guides/search/hybrid-search Combine two or more retrieval signals in Pinecone with a filter that narrows a ranking, or by fusing separate searches with reciprocal rank fusion. Hybrid search combines two or more retrieval signals so your results benefit from each. Full-text search (BM25) and sparse-vector search match specific terms like product codes, error strings, and names. Semantic search (dense vectors) matches on meaning, so a query still finds an answer phrased with different words. Each method misses what the others catch, and hybrid search closes that gap. ## Combine signals The following patterns differ in where the signals meet. A filter can serve as one of them: [metadata filtering](/guides/search/filter-by-metadata) narrows the candidate pool before ranking, so an out-of-scope document can't compete for a result slot. | Pattern | How it works | When to use it | | - | - | - | | Filter, then rank | A filter narrows the candidates, then any ranking clause scores what remains, all in one request. The filter can be a [metadata filter](/guides/search/filter-by-metadata) on any filterable field, or a [text-match filter](/guides/search/filter-by-metadata#text-match-filters) (`$match_phrase`, `$match_all`, `$match_any`) on a full-text field. The ranking clause can score the same `string` field with `embed`, or score a `dense_vector`, `sparse_vector`, or full-text field. | Document and text workloads on the Documents API. One index, one call, and no score normalization. | | Client-side fusion | Run separate searches, then merge any number of their ranked lists with [reciprocal rank fusion (RRF)](/guides/search/reciprocal-rank-fusion). | When you want every signal to contribute to the ranking rather than only narrow the pool. | RRF is a fusion method, not a synonym for hybrid search. It's one way to merge ranked lists, while "hybrid search" is the broader approach of combining signals. See [Reciprocal rank fusion](/guides/search/reciprocal-rank-fusion). ## Set up an index For a new document or text workload, use the [Documents API](/guides/get-started/documents-api). Declare one or more `string` fields with `full_text_search`, then add the dense side: * **Integrated embedding**: Add `embed` to a `string` field, so Pinecone indexes the text for full-text search and embeds it for semantic search. See [Integrated embedding](/guides/search/integrated-embedding). * **Your own vectors**: Declare a `dense_vector` field alongside the full-text fields. See [Bring your own vectors](/guides/search/bring-your-own-vectors) and the full-text search [example schemas](/guides/search/full-text-search#example-schemas). If you [converted a legacy vector index](/guides/indexes/convert-an-index) that held both dense and sparse vectors, the new index has a separate field for each, plus any `string` field you gave `full_text_search`. The legacy combined dense and sparse query doesn't carry over, because a document search ranks by one scoring type per request. Combine them with one of the patterns above. For a legacy vector index, see [Hybrid search on a single index](/guides/legacy/vectors-api/hybrid-search-single-index) and [Hybrid search on separate indexes](/guides/legacy/vectors-api/hybrid-search-separate-indexes). # Integrated embedding Source: https://docs.pinecone.io/guides/search/integrated-embedding Declare embed or sparse_embed on a string field so Pinecone embeds your text on a document index, and upsert and search with plain text instead of vectors. Embedding converts text into a vector that captures its meaning. Instead of generating those vectors yourself, you can have Pinecone embed a `string` field's text for you. Add an `embed` (dense) or `sparse_embed` (learned-sparse) object to the field, and Pinecone embeds the text when you upsert or update a [document](/guides/get-started/key-terms#document), and embeds the query text when you search that field. You send and search with plain text and never handle vectors. This is the same integrated embedding that the [Create an index with integrated embedding](/reference/api/2026-07/control-plane/create_for_model) operation provides for the legacy Records API, brought to document indexes, where it composes with full-text search on the same field. Integrated embedding requires API version `2026-07`. Send `X-Pinecone-Api-Version: 2026-07` on REST requests, or use an SDK that supports it: Python `10.1.0` or later, Node.js `9.1.0` or later, or Go `7.1.0` or later. > [!NOTE] > > Bring Your Own Cloud (BYOC) indexes can't declare `embed` or `sparse_embed`. ## Declare an embedded field Add `embed`, `sparse_embed`, or both to a `string` field, inside `schema.fields` in the [create-index request](/guides/search/full-text-search#example-schemas). Every key inside them is optional: an empty `{}` uses the platform default model at its default dimension and metric. Pinecone resolves and fixes the model, dimension, and metric at creation, and returns them when you describe the index. > [!TIP] > > You can also create an index with integrated embedding in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/schema-create-index). ```json Default models theme={null} { "chunk_text": { "type": "string", "embed": {}, "sparse_embed": {} } } ``` ```json Chosen model and dimension theme={null} { "chunk_text": { "type": "string", "embed": { "model": "llama-text-embed-v2", "dimension": 512 } } } ``` * `embed` takes a hosted dense model (default [`llama-text-embed-v2`](/models/llama-text-embed-v2)) and optional `dimension`, `metric`, [`processing_location`](/guides/indexes/processing-locations), and `write_parameters`/`read_parameters` (model parameters applied when embedding on write and on query, such as `truncate` or [`task_type`](#task-types) for `gemini-embedding-2`). * `sparse_embed` takes a hosted sparse model (default [`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0)) and optional `write_parameters`/`read_parameters`. Sparse embeddings have no dimension or metric. * An `embed` field uses the index's single dense slot, and a `sparse_embed` field uses its single sparse slot. So an index has at most one of each, and an embedded field can't coexist with a `dense_vector` or `sparse_vector` field of the same type (dense or sparse). To compare the hosted models and the dimensions each one supports, see the [model gallery](/models/overview). `llama-text-embed-v2` takes one of a fixed set of dimensions, while `gemini-embedding-2` and the `text-embedding-3` models take any integer in a range. The embedding configuration is fixed at creation: you can't add, remove, or change `embed` or `sparse_embed` on an existing index. ## Text storage and full-text search By default (`store_text: true`), Pinecone stores the field's text and returns it via `include_fields`. It also indexes the text for full-text search, so a `string` field with `embed` is BM25-searchable unless you opt out. Set `store_text: false` to embed the text without storing it. A field with `store_text: false`: * can't declare `full_text_search`. * can't be scored with `text` or `query_string`, or matched with `$match_phrase`, `$match_all`, or `$match_any`. * still supports `embed` and `sparse_embed` scoring. * returns a `400` if named in `include_fields` on search or fetch. `["*"]` leaves it out. To search one chunk field by dense, learned-sparse, and BM25, declare all three aspects: ```json All three aspects theme={null} { "chunk_text": { "type": "string", "embed": {}, "sparse_embed": {}, "full_text_search": {} } } ``` ### Limits * A document and a single request are each limited to 2 MB. On an index that embeds text, that request limit also counts the vectors Pinecone derives from the text. * An embedded value can be up to 100 KB, whether or not the text is stored. A stored value is also limited to 10,000 tokens after tokenization. * Each model embeds only up to its max tokens, listed in the [model gallery](/models/overview). For `pinecone-sparse-english-v0`, that's its [`max_tokens_per_sequence`](/models/pinecone-sparse-english-v0#parameters) parameter. Longer values are truncated by default. For a dense `embed` field, setting `truncate: NONE` rejects an over-length value with a `400` instead. The full value is still stored and returned when `store_text` is `true`. * Truncation applies only to embedding, so a stored value over 10,000 tokens is rejected with a `400` even with `truncate: END`. To embed longer text, split it into smaller documents, or set `store_text: false` to embed it without storing it. * The query text in an `embed` or `sparse_embed` clause is limited to 10,000 bytes. A longer query is rejected with a `400`, not truncated. ## Upsert and search embedded fields ### Upsert Upsert documents with plain text on the embedded field. You don't supply vectors, and Pinecone embeds the text on write. A few rules apply: * When the schema declares `embed` or `sparse_embed`, each upsert or by-ID update is embedded in one call, so it's capped at 96 documents instead of 1,000, even when a request sets only metadata. * A dense `embed` field must appear in every document. Omitting it, or removing it in an update, is rejected with a `400`. A `sparse_embed`-only field is optional, so you can omit or remove it. * A vector or an empty string on an embedded field is rejected with a `400`. * Update is a partial patch, so a field you don't set is left unchanged. A by-filter update can't set an embedded field; patch it by document ID. * An update to an `_id` that doesn't exist has no effect, but any text it sets is still embedded and metered. To add a new document, upsert it. * An upsert or update that embeds text reports the tokens it consumed as `usage.embed_total_tokens`. It's one total across all fields and models, so a field with both `embed` and `sparse_embed` reports the dense and sparse tokens added together. Billing and [monthly limits](/reference/api/database-limits/rate-limits#monthly-usage-limits) count tokens per model, so sparse tokens count toward the field's sparse model, not its dense model. ```python Python theme={null} index.documents.upsert( namespace="example-namespace", documents=[ {"_id": "doc1", "chunk_text": "Vitamin D supports bone health and immune function."}, ], ) ``` ```javascript JavaScript theme={null} const index = pc.index({ name: 'INDEX_NAME', namespace: 'example-namespace' }); await index.documents.upsert({ documents: [ { _id: 'doc1', chunk_text: 'Vitamin D supports bone health and immune function.' }, ], }); ``` ```go Go theme={null} idx, _ := pc.DescribeIndex(ctx, "INDEX_NAME") conn, _ := pc.Index(pinecone.NewIndexConnParams{Host: idx.Host, Namespace: "example-namespace"}) _, err := conn.UpsertDocuments(ctx, &pinecone.UpsertDocumentsRequest{ Documents: []pinecone.Document{ {"_id": "doc1", "chunk_text": "Vitamin D supports bone health and immune function."}, }, }) if err != nil { log.Fatal(err) } ``` > [!NOTE] > > You can't [bulk import](/guides/data/import-data) into an index with an `embed` or `sparse_embed` field. Add text through upsert or update instead. ### Search To search, pick the `embed` or `sparse_embed` scoring method and pass query text. Pinecone embeds the query with the field's frozen model and ranks by similarity. ```python Python theme={null} response = index.documents.search( namespace="example-namespace", top_k=5, score_by=[ {"type": "embed", "fields": ["chunk_text"], "query": "how does vitamin D help the body"} ], include_fields=["chunk_text"], ) ``` ```javascript JavaScript theme={null} const index = pc.index({ name: 'INDEX_NAME', namespace: 'example-namespace' }); const response = await index.documents.search({ topK: 5, scoreBy: [ { type: 'embed', fields: ['chunk_text'], query: 'how does vitamin D help the body' }, ], includeFields: ['chunk_text'], }); ``` ```go Go theme={null} idx, _ := pc.DescribeIndex(ctx, "INDEX_NAME") conn, _ := pc.Index(pinecone.NewIndexConnParams{Host: idx.Host, Namespace: "example-namespace"}) query := "how does vitamin D help the body" response, err := conn.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{ TopK: 5, ScoreBy: []pinecone.DocumentScoringMethod{ {Type: pinecone.DocumentScoringTypeEmbed, Fields: []string{"chunk_text"}, Query: &query}, }, IncludeFields: []string{"chunk_text"}, }) if err != nil { log.Fatal(err) } fmt.Println(response) ``` ```bash curl theme={null} curl -X POST "https://$INDEX_HOST/namespaces/example-namespace/documents/search" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "top_k": 5, "score_by": [ { "type": "embed", "fields": ["chunk_text"], "query": "how does vitamin D help the body" } ], "include_fields": ["chunk_text"] }' ``` Pinecone returns the stored text and any metadata you request with `include_fields`. The vectors it derives from your text are internal and aren't returned. The search response reports the query's embedding usage as `usage.embed_total_tokens`. A `sparse_embed` query is embedded in-process, so it reports `0`. An `embed` or `sparse_embed` clause must be the only clause in `score_by`. You can still combine signals, because a stored embedded field is also full-text-searchable. Rank with an `embed` `score_by`, then narrow the results with a `$match_phrase`, `$match_all`, or `$match_any` filter on the same field (see [Full-text search](/guides/search/full-text-search#search-examples)). To fuse two full rankings instead, run separate searches and merge them with [reciprocal rank fusion](/guides/search/reciprocal-rank-fusion). ## Embed with text-embedding-3 [`text-embedding-3-small`](/models/text-embedding-3-small) and [`text-embedding-3-large`](/models/text-embedding-3-large) are dense models from OpenAI that are available only on document indexes. Pinecone embeds text for them through Microsoft Azure. Each model's page lists its dimensions, token limit, metrics, and parameters. The models are available on every plan. They process text in the `global` [processing location](/guides/indexes/processing-locations) by default, and you can set `processing_location` to `us` on the Standard and Enterprise plans. For monthly and per-minute token limits, see [Rate limits](/reference/api/database-limits/rate-limits). This field embeds with `text-embedding-3-large` at 1,024 dimensions: ```json Shortened large embeddings theme={null} { "chunk_text": { "type": "string", "embed": { "model": "text-embedding-3-large", "dimension": 1024 } } } ``` ## Embed with gemini-embedding-2 [`gemini-embedding-2`](/models/gemini-embedding-2) is a dense model from Google that's available only on document indexes. Pinecone embeds text for it through Google Vertex AI. The model page lists its dimensions, token limit, metric, and parameters. The model isn't available on the Starter plan. Creating an index with it on Starter returns a `403` that names the field and model. If your organization moves to the Starter plan, its existing `gemini-embedding-2` indexes stay, but upserts and searches on them return a `403` until you upgrade again. For monthly and per-minute token limits, see [Rate limits](/reference/api/database-limits/rate-limits). ### Task types `gemini-embedding-2` embeds text differently depending on what the embedding is for. You choose this with the `task_type` parameter. Each task belongs to one of three kinds: * **Write task**: `retrieval_document` embeds the stored text of a field you search. * **Query tasks**: These embed search queries against a `retrieval_document` field. * **Symmetric tasks**: These embed stored text and queries the same way, for comparing texts with each other rather than searching. Pinecone adds the task to each value and query as the short prompt Gemini expects, so you send plain text. For every task type, what it's for, and its prompt, see [Task types](/models/gemini-embedding-2#task-types) on the model page. ### Set task types on the field Set `task_type` in the field's `write_parameters` and `read_parameters`: * `write_parameters.task_type` sets how Pinecone embeds the stored text. It defaults to `retrieval_document` and accepts `retrieval_document` or a symmetric task. A query task is rejected with a `400`. * `read_parameters.task_type` sets the default task for queries. If you don't set it, it follows the write task: `retrieval_query` for a `retrieval_document` field, or the same task for a symmetric field. * A `retrieval_document` field accepts any query task on read. A symmetric field accepts only its own task, so a `clustering` field is always searched with `clustering`. * The write task is fixed at creation, like the rest of the embedding configuration. An index has one `embed` field, so to embed the same text for a different write task, such as `retrieval_document` and `clustering`, create a second index. This field stores articles for search and embeds queries as questions by default: ```json Questions against articles theme={null} { "body": { "type": "string", "embed": { "model": "gemini-embedding-2", "dimension": 768, "read_parameters": { "task_type": "question_answering" } } } } ``` This field embeds support tickets for clustering, and its queries use `clustering` too: ```json Clustered tickets theme={null} { "ticket_text": { "type": "string", "embed": { "model": "gemini-embedding-2", "write_parameters": { "task_type": "clustering" } } } } ``` When you describe the index, the field's `write_parameters` and `read_parameters` show the resolved task types. ### Override the task for one search To embed one search's query with a different task, set `parameters` on the `embed` clause. It overrides the field's `read_parameters` for that search only. The Python SDK `10.3.0`, Node.js SDK `9.2.0`, and Go SDK `7.2.0` and later support `parameters`. For example, this search checks a statement against the `body` field from the preceding example, whose default query task is `question_answering`: ```python Python theme={null} response = index.documents.search( namespace="example-namespace", top_k=5, score_by=[ { "type": "embed", "fields": ["body"], "query": "Is the Eiffel Tower taller than 300 m?", "parameters": {"task_type": "fact_verification"}, } ], include_fields=["body"], ) ``` ```javascript JavaScript theme={null} const response = await index.documents.search({ topK: 5, scoreBy: [ { type: 'embed', fields: ['body'], query: 'Is the Eiffel Tower taller than 300 m?', parameters: { task_type: 'fact_verification' }, }, ], includeFields: ['body'], }); ``` ```go Go theme={null} query := "Is the Eiffel Tower taller than 300 m?" response, err := conn.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{ TopK: 5, ScoreBy: []pinecone.DocumentScoringMethod{ { Type: pinecone.DocumentScoringTypeEmbed, Fields: []string{"body"}, Query: &query, Parameters: map[string]interface{}{"task_type": "fact_verification"}, }, }, IncludeFields: []string{"body"}, }) if err != nil { log.Fatal(err) } fmt.Println(response) ``` ```bash curl theme={null} curl -X POST "https://$INDEX_HOST/namespaces/example-namespace/documents/search" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "top_k": 5, "score_by": [ { "type": "embed", "fields": ["body"], "query": "Is the Eiffel Tower taller than 300 m?", "parameters": { "task_type": "fact_verification" } } ], "include_fields": ["body"] }' ``` These rules apply to `parameters`: * Only `embed` clauses take `parameters`, and only `task_type` can be set per search. Any other key, such as `truncate`, is rejected with a `400`. * The task must be one the field accepts on read. A query task on a symmetric field, or `retrieval_document` on any field, is rejected with a `400` that names the tasks the field allows. * A model without task types, such as `llama-text-embed-v2`, rejects `parameters.task_type` with a `400`. * An empty `parameters` object has no effect. * Upserts and updates don't take a per-request task. Stored text always uses the field's write task. ## Find a model's parameters Each model's page in the [model gallery](/models/overview) lists the parameters it accepts. The [List models](/reference/api/latest/inference/list-available-models) operation also returns each model's `supported_parameters` with their accepted values. It doesn't say which parameters apply on write, on read, or per search, so use the rules on this page for `task_type` and [Processing locations](/guides/indexes/processing-locations) for `processing_location`. List models doesn't require an API key. # 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. > [!NOTE] > > The examples on this page use the [Documents API](/guides/get-started/documents-api). 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 isn't 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. You run each search separately, then apply RRF to their results in your client. ## 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 strong default that works without normalizing scores or tuning per-signal weights. Combining a keyword search with a dense search this way is the client-side fusion approach to [hybrid search](/guides/search/hybrid-search): RRF is the fusion method, applied in your client after the searches run. ## 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.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", "fields": ["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", "fields": ["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. > [!NOTE] > > 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 with text](/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/indexes/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/indexes/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/indexes/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/v7/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/indexes/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: 2026-07" \ -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 results](/reference/api/latest/inference/rerank-results) 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/v7/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: 2026-07" \ -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-results), 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."`. > [!NOTE] > > 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/v7/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: 2026-07" \ -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: > [!NOTE] > > 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-results) on a field other than `documents.text`, provide the `rank_fields` parameter to specify the fields on which to rerank. > [!NOTE] > > [`bge-reranker-v2-m3`](/models/bge-reranker-v2-m3) and [`pinecone-rerank-v0`](/models/pinecone-rerank-v0) support only a single rerank field. [`cohere-rerank-4-fast`](/models/cohere-rerank-4-fast) supports 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/v7/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: 2026-07" \ -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 these reranking models: * [`cohere-rerank-4-fast`](/models/cohere-rerank-4-fast) * [`bge-reranker-v2-m3`](/models/bge-reranker-v2-m3) * [`pinecone-rerank-v0`](/models/pinecone-rerank-v0) (deprecated) Each model's page lists the parameters it accepts and its specs, such as max tokens, max documents per request, and plan. To compare the models, see the [model gallery](/models/overview). > [!NOTE] > > To understand how cost is calculated for reranking, see [Reranking cost](/guides/cost/understand-cost#reranking). To get model details via the API, see [List models](/reference/api/latest/inference/list-available-models) and [Describe a model](/reference/api/latest/inference/describe-a-model). # 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-vector, and hybrid. Pinecone supports four retrieval approaches. Three of them rank on a signal the index declares a field for, and hybrid search combines two or more of them. One document index can declare fields for all three, so the choice is mostly about which signal should order your results. ## Choose an approach | Approach | Ranks on | Index declares | Reach for it when | | - | - | - | - | | [Full-text search](/guides/search/full-text-search) | BM25 token overlap, with optional Lucene query syntax | A `string` field with `full_text_search` | Queries mostly share exact words with the data, such as product names, error strings, source code, or identifiers | | [Semantic search](/guides/search/semantic-search) | Dense-vector similarity, which captures meaning rather than wording | A `dense_vector` field, or a `string` field with [`embed`](/guides/search/integrated-embedding) | Queries are natural language, and a synonym or a paraphrase should still match | | [Sparse-vector search](/guides/search/sparse-vector-search) | Per-token weights | A `sparse_vector` field, or a `string` field with [`sparse_embed`](/guides/search/integrated-embedding) | A sparse model such as [`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0) produces the representation, or your application produces its own sparse vectors | Full-text search and sparse-vector search both rank on tokens. Full-text search matches tokens exactly, unless a field opts into [stemming or other text processing](/guides/search/full-text-search/text-processing). Sparse-vector search weights each token in your documents, which puts it between full-text search and semantic search. For general keyword retrieval, start with full-text search. ## Hybrid search Hybrid search combines two or more signals in a single workflow. It isn't a field type, so an index declares nothing extra for it, and any index whose schema covers at least two signals can serve it. Reach for it when no single signal orders results well, as in a catalog where part numbers and descriptive phrases are both relevant. Full-text with dense is the common pairing on a document index, and sparse with dense is what a [legacy vector index](/guides/legacy/vectors-api/hybrid-search-single-index) runs, but any combination works, including all three at once. A [metadata or text-match filter](/guides/search/filter-by-metadata) can also serve as one of the signals, narrowing the pool before another one ranks what's left. See [Hybrid search](/guides/search/hybrid-search) for the patterns that combine them. ## Tune search Each of these works with any approach: * [Filter by metadata](/guides/search/filter-by-metadata) narrows the candidate pool before ranking, so an out-of-scope document can't take a result slot. [Text-match filters](/guides/search/filter-by-metadata#text-match-filters) (`$match_phrase`, `$match_all`, `$match_any`) do the same on full-text fields. * [Rerank results](/guides/search/rerank-results) reorders what a search returns, using a model that reads the query and the document together. * [Parallel queries](/guides/optimize/increase-throughput#parallel-queries) raise throughput when you run many searches at once. Once you've chosen an approach, see [Data modeling](/guides/indexes/data-modeling) to structure your documents or records, then [Create an index](/guides/indexes/create-an-index) to set it up. > [!TIP] > > Searches consume [read units (RUs)](/guides/cost/understand-cost#read-units). See [Understand Pinecone cost](/guides/cost/understand-cost#query) for how query cost is calculated, [Pricing](https://www.pinecone.io/pricing/) for rates, and [Query limits](/reference/api/database-limits/operation-limits) for `top_k` and result-size limits. # Semantic search Source: https://docs.pinecone.io/guides/search/semantic-search Run semantic search in Pinecone over dense vectors in a document index, querying with text or with a dense vector you generate. Semantic search finds the documents in an [index with dense vectors](/guides/indexes/index-data-overview#indexes-with-dense-vectors) that are most similar in meaning and context to a query. It's also called nearest neighbor search, similarity search, or 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. For a legacy vector index, see [Query vectors](/guides/legacy/vectors-api/query-vectors). For a legacy integrated index, see [Search with text](/guides/legacy/records-api/search-with-text). ## Search a document index In a [document index](/guides/indexes/data-modeling#documents), you choose how to score each search with a clause in `score_by`. Use an `embed` clause to search with text, or a `dense_vector` clause to search with a dense vector you generate yourself. ### Search with text To search with text, the `string` field must declare `embed`, which enables [integrated embedding](/guides/search/integrated-embedding). Pinecone embeds your query text with the field's model. For example, this searches the `chunk_text` field of an index whose schema declares `"chunk_text": {"type": "string", "embed": {}}` and returns the 2 documents most semantically related to "Disease prevention": ```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/indexes/target-an-index index = pc.index(host="INDEX_HOST") results = index.documents.search( namespace="example-namespace", top_k=2, score_by=[ {"type": "embed", "fields": ["chunk_text"], "query": "Disease prevention"} ], include_fields=["chunk_text", "category"], ) ``` ```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/indexes/target-an-index const index = pc.index({ host: "INDEX_HOST", namespace: "example-namespace" }) const results = await index.documents.search({ topK: 2, scoreBy: [ { type: 'embed', fields: ['chunk_text'], query: 'Disease prevention' }, ], includeFields: ['chunk_text', 'category'], }) console.log(results) ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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/indexes/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) } query := "Disease prevention" res, err := idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{ TopK: 2, ScoreBy: []pinecone.DocumentScoringMethod{ {Type: pinecone.DocumentScoringTypeEmbed, Fields: []string{"chunk_text"}, Query: &query}, }, IncludeFields: []string{"chunk_text", "category"}, }) if err != nil { log.Fatalf("Failed to search documents: %v", err) } fmt.Println(prettifyStruct(res)) } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/namespaces/example-namespace/documents/search" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "top_k": 2, "score_by": [ { "type": "embed", "fields": ["chunk_text"], "query": "Disease prevention" } ], "include_fields": ["chunk_text", "category"] }' ``` ### Search with a dense vector To search a `dense_vector` field, pass a `dense_vector` clause in `score_by` with the query's dense vector. Generate the query vector with the same embedding model you used at upsert. For example, this searches the `embedding` field of the [`articles-hybrid` schema](/guides/search/full-text-search#example-schemas), so the query vector must have 1536 dimensions: ```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/indexes/target-an-index index = pc.index(host="INDEX_HOST") # Replace with your query embedding, which must match the index's dimension (1536 in this example) query_vector = [0.1] * 1536 results = index.documents.search( namespace="articles", top_k=3, score_by=[ { "type": "dense_vector", "fields": ["embedding"], "values": query_vector, } ], include_fields=["title"], ) ``` ```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/indexes/target-an-index const index = pc.index({ host: "INDEX_HOST", namespace: "articles" }) // Replace with your query embedding, which must match the index's dimension (1536 in this example) const queryVector = new Array(1536).fill(0.1) const results = await index.documents.search({ topK: 3, scoreBy: [ { type: 'dense_vector', fields: ['embedding'], values: queryVector }, ], includeFields: ['title'], }) console.log(results) ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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/indexes/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "articles"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } // Replace with your query embedding, which must match the index's dimension (1536 in this example) queryVector := make([]float32, 1536) for i := range queryVector { queryVector[i] = 0.1 } res, err := idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{ TopK: 3, ScoreBy: []pinecone.DocumentScoringMethod{ {Type: pinecone.DocumentScoringTypeDenseVector, Fields: []string{"embedding"}, Values: &queryVector}, }, IncludeFields: []string{"title"}, }) if err != nil { log.Fatalf("Failed to search documents: %v", err) } fmt.Println(prettifyStruct(res)) } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" # Stand-in built with jq. Replace with your query embedding, which must match the index's dimension (1536 in this example) QUERY_VECTOR=$(jq -nc '[range(1536) | 0.1]') curl "https://$INDEX_HOST/namespaces/articles/documents/search" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "top_k": 3, "score_by": [ { "type": "dense_vector", "fields": ["embedding"], "values": '"$QUERY_VECTOR"' } ], "include_fields": ["title"] }' ``` # Sparse-vector search Source: https://docs.pinecone.io/guides/search/sparse-vector-search Run sparse-vector search in Pinecone over a document index, querying with text or with a sparse vector you generate. This page shows you how to search an [index with sparse vectors](/guides/indexes/index-data-overview#sparse-vector-search) for documents that most exactly match the words or phrases in a query. > [!NOTE] > > 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 search (this page) is a distinct retrieval mode. Reach for it when you want token-weighted retrieval with sparse vectors, either generated by Pinecone from a `sparse_embed` field ([`pinecone-sparse-english-v0`](/models/pinecone-sparse-english-v0) by default) or produced by your own sparse encoder. Sparse-vector 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 documents scored highest. For a legacy vector index, see [Query vectors](/guides/legacy/vectors-api/query-vectors#query-with-sparse-vectors). For a legacy integrated index, see [Search with text](/guides/legacy/records-api/search-with-text#search-with-sparse-embedding). ## Search a document index In a [document index](/guides/indexes/data-modeling#documents), you choose how to score each search with a clause in `score_by`. Use a `sparse_embed` clause to search with text, or a `sparse_vector` clause to search with a sparse vector you generate yourself. ### Search with text To search with text, the `string` field must declare `sparse_embed`, which enables [integrated embedding](/guides/search/integrated-embedding). Pinecone converts your query text to a sparse vector with the field's model. For example, this searches the `chunk_text` field of an index whose schema declares `"chunk_text": {"type": "string", "sparse_embed": {}}` and returns the 3 documents that best match "What is AAPL's outlook, considering both product launches and market conditions?": ```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/indexes/target-an-index index = pc.index(host="INDEX_HOST") results = index.documents.search( namespace="example-namespace", top_k=3, score_by=[ { "type": "sparse_embed", "fields": ["chunk_text"], "query": "What is AAPL's outlook, considering both product launches and market conditions?", } ], include_fields=["chunk_text", "quarter"], ) ``` ```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/indexes/target-an-index const index = pc.index({ host: "INDEX_HOST", namespace: "example-namespace" }) const results = await index.documents.search({ topK: 3, scoreBy: [ { type: 'sparse_embed', fields: ['chunk_text'], query: "What is AAPL's outlook, considering both product launches and market conditions?", }, ], includeFields: ['chunk_text', 'quarter'], }) console.log(results) ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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/indexes/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) } query := "What is AAPL's outlook, considering both product launches and market conditions?" res, err := idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{ TopK: 3, ScoreBy: []pinecone.DocumentScoringMethod{ {Type: pinecone.DocumentScoringTypeSparseEmbed, Fields: []string{"chunk_text"}, Query: &query}, }, IncludeFields: []string{"chunk_text", "quarter"}, }) if err != nil { log.Fatalf("Failed to search documents: %v", err) } fmt.Println(prettifyStruct(res)) } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/namespaces/example-namespace/documents/search" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "top_k": 3, "score_by": [ { "type": "sparse_embed", "fields": ["chunk_text"], "query": "What is AAPL'\''s outlook, considering both product launches and market conditions?" } ], "include_fields": ["chunk_text", "quarter"] }' ``` To require specific terms in each result, add a `$match_all` [text-match filter](/guides/search/filter-by-metadata#text-match-filters) on the same field, for example, `"filter": {"chunk_text": {"$match_all": "AAPL Q4"}}`. This works because Pinecone stores the field's text and indexes it for full-text search unless the field sets `store_text: false`. ### Search with a sparse vector To search a `sparse_vector` field, pass a `sparse_vector` clause in `score_by` with the query's sparse vector, produced by the same encoder you used at upsert. For example, this searches the `sparse_embedding` field of the [`articles-hybrid` schema](/guides/search/full-text-search#example-schemas): ```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/indexes/target-an-index index = pc.index(host="INDEX_HOST") results = index.documents.search( namespace="articles", top_k=3, score_by=[ { "type": "sparse_vector", "fields": ["sparse_embedding"], "sparse_values": {"indices": [10, 45, 16], "values": [0.5, 0.5, 0.2]}, } ], include_fields=["title"], ) ``` ```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/indexes/target-an-index const index = pc.index({ host: "INDEX_HOST", namespace: "articles" }) const results = await index.documents.search({ topK: 3, scoreBy: [ { type: 'sparse_vector', fields: ['sparse_embedding'], sparseValues: { indices: [10, 45, 16], values: [0.5, 0.5, 0.2] }, }, ], includeFields: ['title'], }) console.log(results) ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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/indexes/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "articles"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } res, err := idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{ TopK: 3, ScoreBy: []pinecone.DocumentScoringMethod{ { Type: pinecone.DocumentScoringTypeSparseVector, Fields: []string{"sparse_embedding"}, SparseValues: &pinecone.SparseValues{ Indices: []uint32{10, 45, 16}, Values: []float32{0.5, 0.5, 0.2}, }, }, }, IncludeFields: []string{"title"}, }) if err != nil { log.Fatalf("Failed to search documents: %v", err) } fmt.Println(prettifyStruct(res)) } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/namespaces/articles/documents/search" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "top_k": 3, "score_by": [ { "type": "sparse_vector", "fields": ["sparse_embedding"], "sparse_values": { "indices": [10, 45, 16], "values": [0.5, 0.5, 0.2] } } ], "include_fields": ["title"] }' ``` # Integrate with Amazon S3 Source: https://docs.pinecone.io/guides/storage-integrations/integrate-with-amazon-s3 Set up a Pinecone storage integration with an Amazon S3 bucket using an IAM role to bulk import data into indexes and export audit logs. > [!NOTE] > > 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/data/import-data) from your Amazon S3 bucket into a Pinecone index hosted on AWS, or to [export audit logs](/admin/security/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/data/import-data) and [exporting audit logs](/admin/security/configure-audit-logs). * `GetObject`: Permission to retrieve objects from an S3 bucket. Required for [importing data](/guides/data/import-data). * `PutObject`: Permission to add an object to an S3 bucket. Required for [exporting audit logs](/admin/security/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](/admin/security/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/*" } ] } ``` > [!NOTE] > > 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 > [!NOTE] > > This step is required for [importing data](/guides/data/import-data). It's not required for [storing audit logs](/admin/security/configure-audit-logs). You can add a storage integration in the Pinecone console or with the API. ### Use the console 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/storage-integrations/integrate-with-amazon-s3#2-set-up-access-using-an-iam-role). 7. Click **Add integration**. ### Use the API > [!NOTE] > > This endpoint requires `X-Pinecone-Api-Version: unstable`. Unstable endpoints can change without notice. Pass the ARN of your IAM role as the `aws_iam_role.role_arn` field: ```bash curl theme={null} curl -sS -X POST "https://api.pinecone.io/storage-integrations" \ -H "Api-Key: ${PINECONE_API_KEY}" \ -H "X-Pinecone-Api-Version: unstable" \ -H "Content-Type: application/json" \ -d '{ "name": "my-s3-integration", "provider": "s3", "aws_iam_role": { "role_arn": "arn:aws:iam::123456789012:role/pinecone-s3-access" } }' ``` Replace the `role_arn` value with the ARN of the [IAM role you created](#2-set-up-access-using-an-iam-role), and `my-s3-integration` with a unique name for the integration. The response includes the integration's `id`, which you need to [import data](/guides/data/import-data), and a `status` of `Validated` or `Invalid`. If Pinecone can't assume the role, the request still succeeds and the integration is created with a `status` of `Invalid`, so check the status before you import. ## Next steps * [Import data](/guides/data/import-data) from your Amazon S3 bucket into a Pinecone index. * [Configure audit logs](/admin/security/configure-audit-logs) to export logs to your Amazon S3 bucket. # Integrate with Azure Blob Storage Source: https://docs.pinecone.io/guides/storage-integrations/integrate-with-azure-blob-storage Set up a Pinecone storage integration with an Azure Blob Storage container using a service principal to bulk import data into your indexes. > [!NOTE] > > 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/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: * Don't 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 You can add a storage integration in the Pinecone console or with the API. ### Use the console 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**. ### Use the API > [!NOTE] > > This endpoint requires `X-Pinecone-Api-Version: unstable`. Unstable endpoints can change without notice. Pass the values you copied from Azure as the `azure_app_credentials` field: ```bash curl theme={null} curl -sS -X POST "https://api.pinecone.io/storage-integrations" \ -H "Api-Key: ${PINECONE_API_KEY}" \ -H "X-Pinecone-Api-Version: unstable" \ -H "Content-Type: application/json" \ -d '{ "name": "my-azure-integration", "provider": "azure_blob", "azure_app_credentials": { "tenant_id": "TENANT_ID", "client_id": "CLIENT_ID", "client_secret": "CLIENT_SECRET" } }' ``` Replace `TENANT_ID`, `CLIENT_ID`, and `CLIENT_SECRET` with the values you copied from Azure, and `my-azure-integration` with a unique name for the integration. The response includes the integration's `id`, which you need to [import data](/guides/data/import-data), and a `status` of `Validated` or `Invalid`. If the credentials are invalid, the request still succeeds and the integration is created with a `status` of `Invalid`, so check the status before you import. ## Next steps [Import data](/guides/data/import-data) from your Azure Blob Storage container into your Pinecone index. # Integrate with Google Cloud Storage Source: https://docs.pinecone.io/guides/storage-integrations/integrate-with-google-cloud-storage Set up a Pinecone storage integration with a Google Cloud Storage bucket using a service account key to bulk import data or export audit logs. > [!NOTE] > > 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/data/import-data) from your bucket into a Pinecone index hosted on AWS, GCP, or Azure, or to [export audit logs](/admin/security/configure-audit-logs) to your bucket. ## 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 one that matches how you use the integration: * [Importing data](/guides/data/import-data): **Storage Object Viewer** or another role that can list and read objects in the bucket. * [Exporting audit logs](/admin/security/configure-audit-logs): **Storage Object User** or another role that can list, create, and delete objects in the bucket. Each time Pinecone checks write access, it writes a test file and then deletes it. **Storage Object Viewer** can't write audit logs. ## 3. Add a storage integration > [!NOTE] > > This step is required for [importing data](/guides/data/import-data). It's not required for exporting audit logs. Instead, enter your service account key when you [configure audit logs](/admin/security/configure-audit-logs). You can add a storage integration in the Pinecone console or with the API. ### Use the console 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 **Service account key JSON** field. 8. Click **Add integration**. ### Use the API > [!NOTE] > > This endpoint requires `X-Pinecone-Api-Version: unstable`. Unstable endpoints can change without notice. Pass the contents of your service account key file as the `gcp_service_account.key_json` field. The following example uses [`jq`](https://jqlang.github.io/jq/) to safely JSON-encode the key file before sending it: ```bash curl theme={null} jq -n --arg key "$(cat service-account-key.json)" \ '{name: "my-gcs-integration", provider: "gcs", gcp_service_account: {key_json: $key}}' \ | curl -sS -X POST "https://api.pinecone.io/storage-integrations" \ -H "Api-Key: ${PINECONE_API_KEY}" \ -H "X-Pinecone-Api-Version: unstable" \ -H "Content-Type: application/json" \ --data @- ``` Replace `service-account-key.json` with the path to the [JSON key file you created](#1-create-a-service-account-and-key), and `my-gcs-integration` with a unique name for the integration. The response includes the integration's `id`, which you need to [import data](/guides/data/import-data), and a `status` of `Validated` or `Invalid`. If the service account key is invalid, the request still succeeds and the integration is created with a `status` of `Invalid`, so check the status before you import. ## Next steps * [Import data](/guides/data/import-data) from your GCS bucket into your Pinecone index. * [Configure audit logs](/admin/security/configure-audit-logs) to export logs to your GCS bucket. # Manage storage integrations Source: https://docs.pinecone.io/guides/storage-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. > [!NOTE] > > 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/storage-integrations/integrate-with-amazon-s3) * [Integrate with Google Cloud Storage](/guides/storage-integrations/integrate-with-google-cloud-storage) * [Integrate with Azure Blob Storage](/guides/storage-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**. # Back up a pod-based index Source: https://docs.pinecone.io/guides/legacy/pod-based-indexes/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. > [!WARNING] > > Pod-based indexes are legacy. Customers who signed up for a Standard or Enterprise plan on or after August 18, 2025 cannot create them. [Create a serverless index](/guides/indexes/create-an-index) instead. Serverless indexes use on-demand read capacity by default, or [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview) for sustained high query rates and workloads of millions of records or more. > [!NOTE] > > SDKs that target API version `2026-07` don't support creating pod-based indexes, and they reject creating an index from a collection. You can still list, describe, and delete existing collections. To create or restore a pod-based index, use an [SDK version](/reference/pinecone-sdks#sdk-versions) that targets an earlier API version, or send an earlier `X-Pinecone-Api-Version` with the REST API. To move a pod-based index to serverless, see [Migrate a pod-based index to serverless](/guides/legacy/pod-based-indexes/migrate-a-pod-based-index-to-serverless). This page describes how to create a static copy of a pod-based index, also known as a [collection](/guides/legacy/pod-based-indexes/understanding-collections). ## Create a collection To create a backup of your pod-based index, use the [Create a collection](/reference/api/latest/control-plane/create_collection) operation. The following example creates a [collection](/guides/legacy/pod-based-indexes/understanding-collections) named `example-collection` from an index named `docs-example`: ```python Python theme={null} # pip install pinecone 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/v7/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" }' ``` > [!TIP] > > 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 a 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 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.db_control.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/v7/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" ``` > [!TIP] > > 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.db_control.client.model.CollectionModel; import java.util.List; 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/v7/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" ``` > [!TIP] > > You can view a list of your collections using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups). > [!TIP] > > 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 a 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 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/v7/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" ``` > [!TIP] > > You can delete a collection using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups). # Restore a pod-based index Source: https://docs.pinecone.io/guides/legacy/pod-based-indexes/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. > [!WARNING] > > Pod-based indexes are legacy. Customers who signed up for a Standard or Enterprise plan on or after August 18, 2025 cannot create them. [Create a serverless index](/guides/indexes/create-an-index) instead. Serverless indexes use on-demand read capacity by default, or [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview) for sustained high query rates and workloads of millions of records or more. > [!NOTE] > > SDKs that target API version `2026-07` don't support creating pod-based indexes, and they reject creating an index from a collection. You can still list, describe, and delete existing collections. To create or restore a pod-based index, use an [SDK version](/reference/pinecone-sdks#sdk-versions) that targets an earlier API version, or send an earlier `X-Pinecone-Api-Version` with the REST API. To move a pod-based index to serverless, see [Migrate a pod-based index to serverless](/guides/legacy/pod-based-indexes/migrate-a-pod-based-index-to-serverless). You can restore a pod-based index by creating a new index from a [collection](/guides/legacy/pod-based-indexes/understanding-collections). ## Create a pod-based index from a collection To create a pod-based index from a [collection](/guides/indexes/back-up-an-index#pod-based-index-backups-using-collections), use the [Create an 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; 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", null, null, null, null, "example-collection", "disabled", null); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" // CreatePodIndex was removed in v7 (API version 2026-07). Use v6 to create pod-based indexes. "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) } indexName := "docs-example" metric := pinecone.Dotproduct deletionProtection := pinecone.DeletionProtectionDisabled sourceCollection := "example-collection" idx, err := pc.CreatePodIndex(ctx, &pinecone.CreatePodIndexRequest{ Name: indexName, Metric: &metric, Dimension: 1536, Environment: "us-east1-gcp", PodType: "p1.x1", SourceCollection: &sourceCollection, DeletionProtection: &deletionProtection, }) if err != nil { log.Fatalf("Failed to create pod-based index: %v", err) } 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/legacy/pod-based-indexes/scale-pod-based-indexes Scale Pinecone pod-based indexes by adding pods or replicas. Pod indexes are legacy and unavailable to new customers, and serverless scales automatically. > [!WARNING] > > Pod-based indexes are legacy. Customers who signed up for a Standard or Enterprise plan on or after August 18, 2025 cannot create them. [Create a serverless index](/guides/indexes/create-an-index) instead. Serverless indexes use on-demand read capacity by default, or [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview) for sustained high query rates and workloads of millions of records or more. 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 scale vertically by increasing the size of your existing pods, or horizontally by adding pods or replicas. This page explains how you can scale your [pod-based indexes](/guides/indexes/index-data-overview#pod-based-indexes) horizontally and vertically. ## Vertical vs. horizontal scaling Vertical scaling increases the size of your existing pods, while horizontal scaling adds pods or replicas. Adding replicas also improves resilience and is an important part of a highly available (HA) setup. The following sections explain both approaches so you can choose the right strategy for your index. ## 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/indexes/index-data-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 doesn't result in downtime. Reads and writes continue uninterrupted during the scaling process, which completes in about 10 minutes. You can't reduce the pod size of your indexes. The number of base pods you specify when you initially create the index is static and can't 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 can't 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. > [tab] Console > > 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 **ellipsis (...) menu > Configure**. > 6. In the dropdown, choose the pod size to use. > 7. Click **Confirm**. > [tab] API > > Use the [Configure an 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/v7/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" > }' > ``` > [!NOTE] > > The size change can take up to 15 minutes to complete. ### Decrease pod size After creating an index, you can't vertically downscale the index/pod size. Instead, you must [create a collection](/guides/legacy/pod-based-indexes/back-up-a-pod-based-index) and then [create a new index from your collection](/guides/legacy/pod-based-indexes/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 an 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 the [Get index stats](/reference/api/latest/data-plane/describeindexstats) operation 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/v7/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 isn't supported directly. However, you can increase the number of pods by using our [collections](/guides/legacy/pod-based-indexes/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/legacy/pod-based-indexes/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/legacy/pod-based-indexes/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/indexes/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/legacy/pod-based-indexes/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 doesn't require downtime. Throughput in terms of queries per second (QPS) scales linearly with the number of replicas per index. #### When to add replicas Add replicas for two reasons: * **Data redundancy and availability**: When you add a replica to your index, the Pinecone controller chooses a zone in the same region that doesn't currently have a replica, up to a maximum of three zones. Your fourth and subsequent replicas are hosted in zones that already have a replica. If your application requires multizone redundancy, we recommend this approach. * **Increased QPS**: Each new replica adds another pod for reading from your index and generally increases QPS by the same amount as a single pod. For example, if you consistently get 25 QPS for a single pod, each replica adds 25 more QPS. > [!WARNING] > > Running a single replica does not provide a highly available setup and is therefore not covered by the uptime guarantees included in Enterprise SLAs. If you don't see an increase in QPS after adding replicas, add multiprocessing to your application to ensure you're running parallel operations. You can use the [Pinecone gRPC SDK](/guides/legacy/vectors-api/upsert-vectors#python-sdk-with-grpc) or your multiprocessing library of choice. #### 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, "disabled"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v7/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/legacy/pod-based-indexes/understanding-collections). # Understanding collections Source: https://docs.pinecone.io/guides/legacy/pod-based-indexes/understanding-collections Legacy documentation for Pinecone collections, a pod-only feature for creating static index snapshots. Collections aren't available for serverless indexes. > [!WARNING] > > Pod-based indexes are legacy. Customers who signed up for a Standard or Enterprise plan on or after August 18, 2025 cannot create them. [Create a serverless index](/guides/indexes/create-an-index) instead. Serverless indexes use on-demand read capacity by default, or [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview) for sustained high query rates and workloads of millions of records or more. > [!NOTE] > > SDKs that target API version `2026-07` don't support creating pod-based indexes, and they reject creating an index from a collection. You can still list, describe, and delete existing collections. To create or restore a pod-based index, use an [SDK version](/reference/pinecone-sdks#sdk-versions) that targets an earlier API version, or send an earlier `X-Pinecone-Api-Version` with the REST API. To move a pod-based index to serverless, see [Migrate a pod-based index to serverless](/guides/legacy/pod-based-indexes/migrate-a-pod-based-index-to-serverless). A collection is a static copy of a pod-based index that only consumes storage. It's a non-queryable representation of a set of records. You can [create a collection](/guides/legacy/pod-based-indexes/back-up-a-pod-based-index) of a pod-based index, and you can [create a new pod-based index from a collection](/guides/legacy/pod-based-indexes/restore-a-pod-based-index). This allows you to restore the index with the same or different configurations. > [!NOTE] > > Once a collection is created, it can't 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. # Create an API key Source: https://docs.pinecone.io/reference/api/2026-07/admin/api-keys/create-an-api-key https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml post /admin/projects/{project_id}/api-keys Create an API key for a project to authenticate Data Plane and Control Plane requests. # Delete an API key Source: https://docs.pinecone.io/reference/api/2026-07/admin/api-keys/delete-an-api-key https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml delete /admin/api-keys/{api_key_id} Delete an API key from a project. # Get API key details Source: https://docs.pinecone.io/reference/api/2026-07/admin/api-keys/get-api-key-details https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml get /admin/api-keys/{api_key_id} Get an API key's details, excluding its secret. # List API keys Source: https://docs.pinecone.io/reference/api/2026-07/admin/api-keys/list-api-keys https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml get /admin/projects/{project_id}/api-keys List all API keys in a project. # Update an API key Source: https://docs.pinecone.io/reference/api/2026-07/admin/api-keys/update-an-api-key https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml patch /admin/api-keys/{api_key_id} Update an API key's name and roles. # Delete an invite Source: https://docs.pinecone.io/reference/api/2026-07/admin/invites/delete-an-invite https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.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. # Get invite details Source: https://docs.pinecone.io/reference/api/2026-07/admin/invites/get-invite-details https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml get /admin/invites/{invite_id} Get an invite in the caller's organization by ID. # Invite a user to the organization Source: https://docs.pinecone.io/reference/api/2026-07/admin/invites/invite-a-user-to-the-organization https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml post /admin/invites Invite a user to the organization by email and grant their initial role bindings. # List invites Source: https://docs.pinecone.io/reference/api/2026-07/admin/invites/list-invites https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml get /admin/invites List pending and expired invites in the caller's organization. # Resend an invite email Source: https://docs.pinecone.io/reference/api/2026-07/admin/invites/resend-an-invite-email https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.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. # Delete an organization Source: https://docs.pinecone.io/reference/api/2026-07/admin/organizations/delete-an-organization https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml delete /admin/organizations/{organization_id} Delete an organization and all its configuration; delete all its projects first. # Get organization details Source: https://docs.pinecone.io/reference/api/2026-07/admin/organizations/get-organization-details https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml get /admin/organizations/{organization_id} Get an organization's details. # List organizations Source: https://docs.pinecone.io/reference/api/2026-07/admin/organizations/list-organizations https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml get /admin/organizations List all organizations associated with an account. # Update an organization Source: https://docs.pinecone.io/reference/api/2026-07/admin/organizations/update-an-organization https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml patch /admin/organizations/{organization_id} Update an organization's name. # Create a new project Source: https://docs.pinecone.io/reference/api/2026-07/admin/projects/create-a-new-project https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml post /admin/projects Create a new project. # Delete a project Source: https://docs.pinecone.io/reference/api/2026-07/admin/projects/delete-a-project https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml delete /admin/projects/{project_id} Delete a project and all its configuration; delete its indexes, assistants, backups, and collections first. # Get project details Source: https://docs.pinecone.io/reference/api/2026-07/admin/projects/get-project-details https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml get /admin/projects/{project_id} Get a project's details. # List projects Source: https://docs.pinecone.io/reference/api/2026-07/admin/projects/list-projects https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml get /admin/projects List all projects in an organization. # Update a project Source: https://docs.pinecone.io/reference/api/2026-07/admin/projects/update-a-project https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml patch /admin/projects/{project_id} Update a project's name, maximum number of Pods, or customer-managed encryption key (CMEK). # Create a service account Source: https://docs.pinecone.io/reference/api/2026-07/admin/service-accounts/create-a-service-account https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml post /admin/service-accounts Create a service account with optional initial role bindings; the client secret is returned only once. # Get service account details Source: https://docs.pinecone.io/reference/api/2026-07/admin/service-accounts/get-service-account-details https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.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. # List service accounts Source: https://docs.pinecone.io/reference/api/2026-07/admin/service-accounts/list-service-accounts https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml get /admin/service-accounts List service accounts in the caller's organization. # Get user details Source: https://docs.pinecone.io/reference/api/2026-07/admin/users/get-user-details https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml get /admin/users/{user_id} Get a user in the caller's organization by ID. # List users in the organization Source: https://docs.pinecone.io/reference/api/2026-07/admin/users/list-users-in-the-organization https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml get /admin/users List users in the caller's organization, optionally filtered by email address. # Remove a user from the organization Source: https://docs.pinecone.io/reference/api/2026-07/admin/users/remove-a-user-from-the-organization https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml delete /admin/users/{user_id} Remove a user from the organization and revoke their role bindings; their Pinecone account is not deleted. # Cancel a conversion job Source: https://docs.pinecone.io/reference/api/2026-07/control-plane/cancel_conversion_job https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_control_2026-07.oas.yaml post /conversion-jobs/{job_id}/cancel Cancel a conversion job that is `Pending` or `InProgress`. The job stops, and the index it was filling is left in the `InitializationFailed` state; delete it to free its name. Cancelling a job that has already ended has no effect. The response is the job as it stands after the request, so a repeated cancel returns the same result. ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" JOB_ID="670e8400-e29b-41d4-a716-446655440001" curl -X POST "https://api.pinecone.io/conversion-jobs/$JOB_ID/cancel" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" \ -H 'accept: application/json' ``` # Configure an index Source: https://docs.pinecone.io/reference/api/2026-07/control-plane/configure_index https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_control_2026-07.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). Updates configuration on an existing index. You can update `deletion_protection`, `tags`, and `read_capacity` (for example, converting from `OnDemand` to `Dedicated`). You can't change the schema here. To change field types or add indexed fields, create a new index and re-upsert. To move a legacy vector index or legacy integrated index onto a document schema, [convert it](/guides/indexes/convert-an-index) into a new document index. This is a partial update: only the fields you include in the request body are modified. Unspecified fields are left unchanged. To clear `tags`, send `"tags": {}`. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) # Enable deletion protection pc.indexes.configure( name="articles", deletion_protection="enabled", ) # Convert read capacity from OnDemand to Dedicated pc.indexes.configure( name="articles", read_capacity={ "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": {"shards": 1, "replicas": 1}, }, }, ) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); // Enable deletion protection await pc.indexes.configure('articles', { deletionProtection: 'enabled', }); // Convert read capacity from OnDemand to Dedicated await pc.indexes.configure('articles', { readCapacity: { mode: 'Dedicated', dedicated: { nodeType: 'b1', scaling: 'Manual', manual: { shards: 1, replicas: 1 }, }, }, }); ``` ```go Go theme={null} package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // Enable deletion protection _, err = pc.ConfigureIndex(ctx, "articles", pinecone.ConfigureIndexParams{ DeletionProtection: pinecone.DeletionProtectionEnabled, }) if err != nil { log.Fatalf("Failed to configure index: %v", err) } // Convert read capacity from OnDemand to Dedicated nodeType := "b1" shards := int32(1) replicas := int32(1) _, err = pc.ConfigureIndex(ctx, "articles", pinecone.ConfigureIndexParams{ ReadCapacity: &pinecone.ReadCapacityParams{ Dedicated: &pinecone.ReadCapacityDedicatedConfig{ NodeType: &nodeType, Scaling: &pinecone.ReadCapacityScaling{ Manual: &pinecone.ReadCapacityManualScaling{ Shards: &shards, Replicas: &replicas, }, }, }, }, }) if err != nil { log.Fatalf("Failed to configure index: %v", err) } } ``` ```hcl Terraform theme={null} # Requires Terraform provider v5.0.0 or later # To configure an index, change deletion_protection, tags, or read_capacity in its # resource block and run `terraform apply`. Terraform updates the index in place. # An index can't switch from dedicated read capacity back to on-demand. resource "pinecone_index" "articles" { name = "articles" deployment = { managed = { cloud = "aws" region = "us-east-1" } } schema = { fields = { title = { string = { full_text_search = {} } } body = { string = { full_text_search = { language = "en", stemming = true, stop_words = true } } } } } # Enable deletion protection deletion_protection = "enabled" # Add or change tags tags = { environment = "production" } # Convert read capacity from on-demand to dedicated. The apply waits until the # dedicated read nodes are ready. read_capacity = { dedicated = { node_type = "b1" replicas = 1 shards = 1 } } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" # Enable deletion protection curl -X PATCH "https://api.pinecone.io/indexes/articles" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "deletion_protection": "enabled" }' # Convert read capacity from OnDemand to Dedicated curl -X PATCH "https://api.pinecone.io/indexes/articles" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 1, "replicas": 1 } } } }' ``` # Convert an index into a document index Source: https://docs.pinecone.io/reference/api/2026-07/control-plane/convert_index https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_control_2026-07.oas.yaml post /indexes/{index_name}/convert Convert a serverless vector index or legacy integrated index into a new document index. The source index isn't changed, and the new index holds a snapshot of the source taken when the job starts. The request returns once the new index is created in the `Initializing` state. Track the job with [Describe a conversion job](https://docs.pinecone.io/reference/api/2026-07/control-plane/describe_conversion_job). If the job fails or is canceled, the index is left in the `InitializationFailed` state with no usable data. Delete it to free its name. A job that fails because of your data is charged for the data it read, and a canceled job isn't charged. For how source records map to the schema, see [Convert an index](https://docs.pinecone.io/guides/index-data/convert-an-index). ```bash Legacy vector index theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl https://api.pinecone.io/indexes/support-tickets/convert \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" \ -H 'Content-Type: application/json' \ -d '{ "name": "support-tickets-docs", "schema": { "fields": { "embedding": { "type": "dense_vector", "dimension": 1024, "metric": "cosine" }, "ticket_text": { "type": "string", "full_text_search": { "language": "en" } } } }, "error_mode": { "on_error": "continue" } }' ``` ```bash Legacy integrated index theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl https://api.pinecone.io/indexes/support-articles/convert \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" \ -H 'Content-Type: application/json' \ -d '{ "name": "support-articles-docs", "schema": { "fields": { "chunk_text": { "type": "string", "embed": { "model": "multilingual-e5-large" } } } } }' ``` # Create a backup of an index Source: https://docs.pinecone.io/reference/api/2026-07/control-plane/create_backup https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_control_2026-07.oas.yaml post /indexes/{index_name}/backups Create a backup of an index. The backup records the schema of the index it is taken from and reports it as `schema`. An index created from the backup with [Create index from backup](https://docs.pinecone.io/reference/api/2026-07/control-plane/create_index_from_backup) inherits that schema. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) backup = pc.backups.create( index_name="docs-example", name="example-backup", description="Monthly backup of production index", ) print(backup) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); const backup = await pc.backups.create('docs-example', { name: 'example-backup', description: 'Monthly backup of production index', }); console.log(backup); ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } backupName := "example-backup" backupDesc := "Monthly backup of production index" backup, err := pc.CreateBackup(ctx, &pinecone.CreateBackupParams{ IndexName: "docs-example", Name: &backupName, Description: &backupDesc, }) if err != nil { log.Fatalf("Failed to create backup: %v", err) } out, err := json.MarshalIndent(backup, "", " ") if err != nil { log.Fatalf("Failed to marshal response: %v", err) } fmt.Println(string(out)) } ``` ```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-07" \ -d '{ "name": "example-backup", "description": "Monthly backup of production index" }' ``` # Create backup schedule Source: https://docs.pinecone.io/reference/api/2026-07/control-plane/create_backup_schedule POST https://api.pinecone.io/indexes/{index_name}/backup-schedules Create a recurring backup schedule for a Pinecone serverless or BYOC index using the API, including daily, weekly, or monthly frequency and retention policy. > [!NOTE] > > This endpoint requires `X-Pinecone-Api-Version: 2026-07`. Create a recurring backup schedule for a serverless or BYOC 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 **index_name** `string` *required* The name of the index to create a backup schedule for. ### Body parameters **name** `string` *required* A human-readable name for the backup schedule. Backups created by the schedule are automatically named `{name}-{ISO8601_timestamp}`. **schedule** `object` *required* The schedule configuration. **schedule properties** **type** `string` *required* The type of schedule. Currently only `time-based` is supported. **frequency** `string` *required* How often backups are created. One of `daily`, `weekly`, or `monthly`. **retention** `object` *required* The retention policy for backups created by this schedule. **retention properties** **expire_after_days** `integer` *required* 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. | ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) schedule = pc.backup_schedules.create( index_name="docs-example", name="example-backup-schedule", frequency="daily", retention_days=7, ) print(schedule) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); const schedule = await pc.backupSchedules.create('docs-example', { name: 'example-backup-schedule', frequency: 'daily', retentionDays: 7, }); console.log(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: 2026-07" \ -H "Content-Type: application/json" \ -d '{ "name": "example-backup-schedule", "schedule": { "type": "time-based", "frequency": "daily" }, "retention": { "expire_after_days": 7 } }' ``` # Create a collection Source: https://docs.pinecone.io/reference/api/2026-07/control-plane/create_collection https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_control_2026-07.oas.yaml post /collections Create a Pinecone collection. Collections are supported only for pod-based indexes. Pod-based indexes cannot be created with API version `2026-07`, so this operation applies to pod-based indexes created with an earlier API version. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) collection = pc.collections.create(name="example-collection", source="docs-example") print(collection.name, collection.status) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); const collection = await pc.collections.create({ name: 'example-collection', source: 'docs-example', }); console.log(collection.name, collection.status); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_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) } fmt.Println(collection.Name, collection.Status) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v5.0.0 or later # The source must be an existing pod-based index resource "pinecone_collection" "example_collection" { name = "example-collection" source = "docs-example" } output "example_collection_status" { value = pinecone_collection.example_collection.status } ``` ```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-07" \ -d '{ "name": "example-collection", "source": "docs-example" }' ``` # Create a legacy integrated index Source: https://docs.pinecone.io/reference/api/2026-07/control-plane/create_for_model https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_control_2026-07.oas.yaml post /indexes/create-for-model Create a legacy integrated index. Legacy integrated indexes created via create-for-model require the legacy Records API. For new work, create a document index with [Create an index](https://docs.pinecone.io/reference/api/2026-07/control-plane/create_index), declaring `embed` or `sparse_embed` on a `string` field to enable integrated embedding on it, and read and write the index through the Documents API. Document indexes support integrated embedding alongside full-text search on the same field, and scoring with `score_by`. 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-07/data-plane/upsert_records) and [search](https://docs.pinecone.io/reference/api/2026-07/data-plane/search_records). The response is this version's index model, with the embedding configuration surfaced as a `semantic_text` field in the index `schema`, named after the `field_map` text entry. Read and write the index through the legacy Records API. For guidance and examples, see [Create an index](https://docs.pinecone.io/guides/index-data/create-an-index#integrated-embedding). ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) index_model = pc.indexes.create_for_model( name="docs-example", cloud="aws", region="us-east-1", embed={ "model": "multilingual-e5-large", "field_map": {"text": "chunk_text"}, }, ) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); const indexModel = await pc.indexes.createForModel({ name: 'docs-example', cloud: 'aws', region: 'us-east-1', embed: { model: 'multilingual-e5-large', fieldMap: { text: 'chunk_text' }, }, }); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.CreateIndexForModel(ctx, &pinecone.CreateIndexForModelRequest{ Name: "docs-example", Cloud: pinecone.CloudAWS, Region: "us-east-1", Embed: pinecone.CreateIndexForModelEmbed{ Model: "multilingual-e5-large", FieldMap: map[string]interface{}{"text": "chunk_text"}, }, }) if err != nil { log.Fatalf("Failed to create index: %v", err) } fmt.Println(idx.Name, idx.Host) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v5.0.0 or later # Creates a legacy integrated index. For new indexes, declare integrated embedding # on a string field of a document index instead (provider v5.1.0 or later). resource "pinecone_index" "docs_example" { name = "docs-example" spec = { serverless = { cloud = "aws" region = "us-east-1" } } embed = { model = "multilingual-e5-large" field_map = { text = "chunk_text" } } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl "https://api.pinecone.io/indexes/create-for-model" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "name": "docs-example", "cloud": "aws", "region": "us-east-1", "embed": { "model": "multilingual-e5-large", "field_map": {"text": "chunk_text"} } }' ``` # Create an index Source: https://docs.pinecone.io/reference/api/2026-07/control-plane/create_index https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_control_2026-07.oas.yaml post /indexes Create a Pinecone index. Define the schema for your index — dense vector, sparse vector, and full-text search fields, and string fields with integrated embedding — and, optionally, the deployment infrastructure (managed serverless or BYOC). The index is a document index, read and written through the Documents API. To enable integrated embedding on a field, declare a `string` field with `embed` (dense) and/or `sparse_embed` (sparse): Pinecone embeds the field's text when documents are written and the query text when a search scores the field. BYOC indexes cannot declare `embed` or `sparse_embed`. **The index schema cannot be modified after creation.** Field types, dimensions, metrics, embedding models, and text-analysis settings are permanent. Choose your schema carefully before creating an index. To create an index from a backup, use [Create index from backup](https://docs.pinecone.io/reference/api/2026-07/control-plane/create_index_from_backup). For guidance and examples, see [Create an index](https://docs.pinecone.io/guides/index-data/create-an-index). [Create a legacy integrated index](https://docs.pinecone.io/reference/api/2026-07/control-plane/create_index_for_model) creates legacy integrated indexes, which require the legacy Records API. The index initializes asynchronously. Before sending data plane requests, poll [Describe an index](/reference/api/2026-07/control-plane/describe_index) until `status.ready` is `true` (and, for `Dedicated` read capacity, until `read_capacity.status.state` is `"Ready"`). The response shows each `full_text_search` field's resolved analyzer settings (`language`, `stemming`, and `stop_words`), including any defaults applied at creation. ## Cloud regions For managed (serverless) indexes, the `cloud` and `region` fields in `deployment` 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 can't be changed after a serverless index is created. > [!NOTE] > > 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](/admin/billing/upgrade-billing-plan). For BYOC indexes, set `deployment.environment` to the environment ID provisioned for your account instead. See [Bring Your Own Cloud](/guides/production/bring-your-own-cloud) for details. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone, SchemaBuilder pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) schema = ( SchemaBuilder() .add_string_field(name="title", full_text_search={}) .add_string_field(name="body", full_text_search={"language": "en", "stemming": True, "stop_words": True}) .build() ) index_model = pc.indexes.create( name="articles", schema=schema, read_capacity={"mode": "OnDemand"}, ) host = index_model.host ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); const indexModel = await pc.indexes.create({ name: 'articles', schema: { fields: { title: { type: 'string', fullTextSearch: {}, }, body: { type: 'string', fullTextSearch: { language: 'en', stemming: true, stopWords: true, }, }, }, }, readCapacity: { mode: 'OnDemand', }, }); const host = indexModel.host; ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } language := "en" stemming := true stopWords := true idx, err := pc.CreateIndex(ctx, &pinecone.CreateIndexRequest{ Name: "articles", Schema: pinecone.IndexSchema{ Fields: map[string]pinecone.IndexSchemaField{ "title": { String: &pinecone.StringField{ FullTextSearch: &pinecone.FullTextSearchConfig{}, }, }, "body": { String: &pinecone.StringField{ FullTextSearch: &pinecone.FullTextSearchConfig{ Language: &language, Stemming: &stemming, StopWords: &stopWords, }, }, }, }, }, ReadCapacity: &pinecone.ReadCapacityParams{ OnDemand: &pinecone.ReadCapacityOnDemandConfig{}, }, }) if err != nil { log.Fatalf("Failed to create index: %v", err) } host := idx.Host fmt.Println(host) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v5.0.0 or later resource "pinecone_index" "articles" { name = "articles" deployment = { managed = { cloud = "aws" region = "us-east-1" } } schema = { fields = { title = { string = { full_text_search = {} } } body = { string = { full_text_search = { language = "en", stemming = true, stop_words = true } } } } } read_capacity = { on_demand = {} } deletion_protection = "disabled" } output "articles_host" { value = pinecone_index.articles.host } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" # EXAMPLE REQUEST 1: On-demand read capacity (default) curl "https://api.pinecone.io/indexes" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "name": "articles", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "title": { "type": "string", "full_text_search": {} }, "body": { "type": "string", "full_text_search": {} } } }, "read_capacity": { "mode": "OnDemand" }, "deletion_protection": "disabled" }' # EXAMPLE REQUEST 2: Dedicated read capacity curl "https://api.pinecone.io/indexes" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "name": "articles-dedicated", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "content": { "type": "string", "full_text_search": {} } } }, "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 1, "replicas": 1 } } }, "deletion_protection": "disabled" }' # EXAMPLE REQUEST 3: Multi-field schema (text + dense + sparse ranking fields) curl "https://api.pinecone.io/indexes" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "name": "articles-multifield", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "title": { "type": "string", "full_text_search": {} }, "body": { "type": "string", "full_text_search": { "language": "en", "stemming": true, "stop_words": true } }, "embedding": { "type": "dense_vector", "dimension": 1536, "metric": "cosine" }, "sparse_embedding": { "type": "sparse_vector" } } } }' # EXAMPLE REQUEST 4: Bring-your-own-cloud (BYOC) deployment. # BYOC indexes support on-demand and dedicated read capacity. This example uses dedicated. curl "https://api.pinecone.io/indexes" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "name": "byoc-index", "deployment": { "deployment_type": "byoc", "environment": "aws-us-east-1-b921.byoc" }, "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 1, "replicas": 1 } } }, "schema": { "fields": { "embedding": { "type": "dense_vector", "dimension": 1536, "metric": "cosine" } } } }' # EXAMPLE REQUEST 5: BYOC deployment with on-demand read capacity. # The index runs on the shared on-demand pool in your BYOC cluster, so no shards or replicas are set. curl "https://api.pinecone.io/indexes" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "name": "byoc-on-demand-index", "deployment": { "deployment_type": "byoc", "environment": "aws-us-east-1-b921.byoc" }, "read_capacity": { "mode": "OnDemand" }, "schema": { "fields": { "embedding": { "type": "dense_vector", "dimension": 1536, "metric": "cosine" } } } }' ``` # Create an index from a backup Source: https://docs.pinecone.io/reference/api/2026-07/control-plane/create_index_from_backup https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_control_2026-07.oas.yaml post /backups/{backup_id}/create-index Create an index from a backup. The restored index inherits the schema of the index the backup was taken from, including its full-text search fields and its embedding configuration (`embed` / `sparse_embed` fields, or the `semantic_text` field of a legacy integrated index created via create-for-model), and the request cannot override it. A backup that carries no `schema` restores an index whose fields are derived from the source index's dimension, metric, and vector type, and reported under the reserved `_values` / `_sparse_values` names. By default, the index is created where the backup was taken: the same cloud and region for a serverless backup, or the same environment for a BYOC backup. To restore a serverless backup into another region of the same cloud, set `deployment` to a `managed` deployment in that region. Cross-cloud restore is not supported, a serverless backup cannot be restored into a BYOC environment, and a BYOC backup can only be restored into the environment it was taken in. You can optionally set `read_capacity` so the restored index is created with dedicated read nodes (DRN) instead of defaulting to on-demand capacity. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) response = pc.create_index_from_backup( backup_id="a65ff585-d987-4da5-a622-72e19a6ed5f4", name="restored-index", tags={ "tag0": "val0", "tag1": "val1", }, deletion_protection="enabled", timeout=-1, # Return the restore job ID without waiting for the index ) print(response) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); const response = await pc.backups.createIndex( 'a65ff585-d987-4da5-a622-72e19a6ed5f4', { name: 'restored-index', tags: { tag0: 'val0', tag1: 'val1', }, deletionProtection: 'enabled', }, ); console.log(response); ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } deletionProtection := pinecone.DeletionProtectionEnabled tags := pinecone.IndexTags{ "tag0": "val0", "tag1": "val1", } response, err := pc.CreateIndexFromBackup(ctx, &pinecone.CreateIndexFromBackupParams{ BackupId: "a65ff585-d987-4da5-a622-72e19a6ed5f4", Name: "restored-index", Tags: &tags, DeletionProtection: &deletionProtection, }) if err != nil { log.Fatalf("Failed to create index from backup: %v", err) } out, err := json.MarshalIndent(response, "", " ") if err != nil { log.Fatalf("Failed to marshal response: %v", err) } fmt.Println(string(out)) } ``` ```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-07" \ -H 'Content-Type: application/json' \ -d '{ "name": "restored-index", "tags": { "tag0": "val0", "tag1": "val1" }, "deletion_protection": "enabled" }' ``` # Delete a backup Source: https://docs.pinecone.io/reference/api/2026-07/control-plane/delete_backup https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_control_2026-07.oas.yaml delete /backups/{backup_id} Delete a backup. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) pc.backups.delete(backup_id="9947520e-d5a1-4418-a78d-9f464c9969da") ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); await pc.backups.delete('9947520e-d5a1-4418-a78d-9f464c9969da'); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } err = pc.DeleteBackup(ctx, "9947520e-d5a1-4418-a78d-9f464c9969da") if err != nil { log.Fatalf("Failed to delete backup: %v", err) } fmt.Println("Backup deleted") } ``` ```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-07" ``` # Delete backup schedule Source: https://docs.pinecone.io/reference/api/2026-07/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. > [!NOTE] > > This endpoint requires `X-Pinecone-Api-Version: 2026-07`. Delete a backup schedule. This does **not** delete any backups that were previously created by the schedule. ### Path parameters **schedule_id** `string` *required* The ID of the backup schedule to delete. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) pc.backup_schedules.delete(schedule_id="SCHEDULE_ID") ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); await pc.backupSchedules.delete('SCHEDULE_ID'); ``` ```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: 2026-07" ``` # Delete a collection Source: https://docs.pinecone.io/reference/api/2026-07/control-plane/delete_collection https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_control_2026-07.oas.yaml delete /collections/{collection_name} Delete an existing collection. Collections are supported only for pod-based indexes. Pod-based indexes cannot be created with API version `2026-07`, so this operation applies to pod-based indexes created with an earlier API version. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) pc.collections.delete(name="example-collection") ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); await pc.collections.delete('example-collection'); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } err = pc.DeleteCollection(ctx, "example-collection") if err != nil { log.Fatalf("Failed to delete collection: %v", err) } fmt.Println("Deleted collection example-collection") } ``` ```hcl Terraform theme={null} # Requires Terraform provider v5.0.0 or later # This block defines the collection. To delete it, either remove the block and run # `terraform apply`, or run: # terraform destroy -target=pinecone_collection.example_collection resource "pinecone_collection" "example_collection" { name = "example-collection" source = "docs-example" } ``` ```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-07" ``` # Delete an index Source: https://docs.pinecone.io/reference/api/2026-07/control-plane/delete_index https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_control_2026-07.oas.yaml delete /indexes/{index_name} Delete an existing index. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) pc.indexes.delete(name="docs-example") ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); await pc.indexes.delete('docs-example'); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } err = pc.DeleteIndex(ctx, "docs-example") if err != nil { log.Fatalf("Failed to delete index: %v", err) } fmt.Println("Deleted index docs-example") } ``` ```hcl Terraform theme={null} # Requires Terraform provider v5.0.0 or later # This block defines the index. To delete it, either remove the block and run # `terraform apply`, or run: # terraform destroy -target=pinecone_index.docs_example # If deletion protection is enabled, first set deletion_protection = "disabled" # and run `terraform apply`, then delete the index. resource "pinecone_index" "docs_example" { name = "docs-example" deployment = { managed = { cloud = "aws" region = "us-east-1" } } schema = { fields = { _values = { dense_vector = { dimension = 1536, metric = "cosine" } } } } deletion_protection = "disabled" } ``` ```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-07" ``` # Describe a backup Source: https://docs.pinecone.io/reference/api/2026-07/control-plane/describe_backup https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_control_2026-07.oas.yaml get /backups/{backup_id} Get a description of a backup. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) backup = pc.backups.describe(backup_id="8c85e612-ed1c-4f97-9f8c-8194e07bcf71") print(backup) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); const backup = await pc.backups.describe('8c85e612-ed1c-4f97-9f8c-8194e07bcf71'); console.log(backup); ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_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) } out, err := json.MarshalIndent(backup, "", " ") if err != nil { log.Fatalf("Failed to marshal response: %v", err) } fmt.Println(string(out)) } ``` ```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-07" \ -H "accept: application/json" ``` # Describe backup schedule Source: https://docs.pinecone.io/reference/api/2026-07/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. > [!NOTE] > > This endpoint requires `X-Pinecone-Api-Version: 2026-07`. Get the details of a specific backup schedule by its ID. ### Path parameters **schedule_id** `string` *required* The ID of the backup schedule. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) schedule = pc.backup_schedules.describe(schedule_id="SCHEDULE_ID") print(schedule) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); const schedule = await pc.backupSchedules.describe('SCHEDULE_ID'); console.log(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: 2026-07" ``` # Describe a collection Source: https://docs.pinecone.io/reference/api/2026-07/control-plane/describe_collection https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_control_2026-07.oas.yaml get /collections/{collection_name} Get a description of a collection. Collections are supported only for pod-based indexes. Pod-based indexes cannot be created with API version `2026-07`, so this operation applies to pod-based indexes created with an earlier API version. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) collection = pc.collections.describe(name="example-collection") print(collection.name, collection.status, collection.dimension, collection.vector_count) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); const collection = await pc.collections.describe('example-collection'); console.log(collection.name, collection.status, collection.dimension, collection.vectorCount); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } collection, err := pc.DescribeCollection(ctx, "example-collection") if err != nil { log.Fatalf("Failed to describe collection: %v", err) } fmt.Println(collection.Name, collection.Status, collection.Dimension, collection.VectorCount) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v5.0.0 or later data "pinecone_collection" "example_collection" { name = "example-collection" } output "example_collection" { value = { status = data.pinecone_collection.example_collection.status dimension = data.pinecone_collection.example_collection.dimension vector_count = data.pinecone_collection.example_collection.vector_count } } ``` ```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: 2026-07" ``` # Describe a conversion job Source: https://docs.pinecone.io/reference/api/2026-07/control-plane/describe_conversion_job https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_control_2026-07.oas.yaml get /conversion-jobs/{job_id} Get the status and progress of a conversion job. ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" JOB_ID="670e8400-e29b-41d4-a716-446655440001" curl "https://api.pinecone.io/conversion-jobs/$JOB_ID" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" \ -H 'accept: application/json' ``` # Describe an index Source: https://docs.pinecone.io/reference/api/2026-07/control-plane/describe_index https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_control_2026-07.oas.yaml get /indexes/{index_name} Get a description of an index. Returns detailed information about a specific index, including its schema, status, host URL, and read capacity. Poll this endpoint after calling [Create an index](/reference/api/2026-07/control-plane/create_index) until `status.ready: true` (and, for `Dedicated` read capacity, `read_capacity.status.state: "Ready"`) before performing data plane operations. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) index_model = pc.indexes.describe(name="articles") print(index_model.status, index_model.schema) host = index_model.host ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); const indexModel = await pc.indexes.describe('articles'); console.log(indexModel.status, indexModel.schema); const host = indexModel.host; ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.DescribeIndex(ctx, "articles") if err != nil { log.Fatalf("Failed to describe index: %v", err) } schema, err := json.Marshal(idx.Schema) if err != nil { log.Fatalf("Failed to marshal schema: %v", err) } fmt.Println(idx.Status.State, string(schema)) host := idx.Host fmt.Println(host) } ``` ```hcl Terraform theme={null} # Requires Terraform provider v5.0.0 or later data "pinecone_index" "articles" { name = "articles" } output "articles_host" { value = data.pinecone_index.articles.host } output "articles_status" { value = data.pinecone_index.articles.status } output "articles_schema" { value = data.pinecone_index.articles.schema } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl "https://api.pinecone.io/indexes/articles" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" ``` # Describe a restore job Source: https://docs.pinecone.io/reference/api/2026-07/control-plane/describe_restore_job https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_control_2026-07.oas.yaml get /restore-jobs/{job_id} Get a description of a restore job. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) restore_job = pc.restore_jobs.describe(job_id="9857add2-99d4-4399-870e-aa7f15d8d326") print(restore_job) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); const restoreJob = await pc.restoreJobs.describe('9857add2-99d4-4399-870e-aa7f15d8d326'); console.log(restoreJob); ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } restoreJob, err := pc.DescribeRestoreJob(ctx, "9857add2-99d4-4399-870e-aa7f15d8d326") if err != nil { log.Fatalf("Failed to describe restore job: %v", err) } out, err := json.MarshalIndent(restoreJob, "", " ") if err != nil { log.Fatalf("Failed to marshal response: %v", err) } fmt.Println(string(out)) } ``` ```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-07" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'accept: application/json' ``` # List backup schedule history Source: https://docs.pinecone.io/reference/api/2026-07/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. > [!NOTE] > > This endpoint requires `X-Pinecone-Api-Version: 2026-07`. 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 **schedule_id** `string` *required* The ID of the backup schedule. ### Query parameters **limit** `integer` The maximum number of results to return. **paginationToken** `string` A token for fetching the next page of results. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) history = pc.backup_schedules.history(schedule_id="SCHEDULE_ID") print(history) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); const history = await pc.backupSchedules.history('SCHEDULE_ID'); console.log(history); ``` ```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: 2026-07" ``` # List backup schedules Source: https://docs.pinecone.io/reference/api/2026-07/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. > [!NOTE] > > This endpoint requires `X-Pinecone-Api-Version: 2026-07`. List all backup schedules configured for a specific index. ### Path parameters **index_name** `string` *required* The name of the index to list backup schedules for. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) schedules = pc.backup_schedules.list(index_name="docs-example") print(schedules) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); const schedules = await pc.backupSchedules.list('docs-example'); console.log(schedules); ``` ```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: 2026-07" ``` # List collections Source: https://docs.pinecone.io/reference/api/2026-07/control-plane/list_collections https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_control_2026-07.oas.yaml get /collections List all collections in a project. Collections are supported only for pod-based indexes. Pod-based indexes cannot be created with API version `2026-07`, so this operation applies to pod-based indexes created with an earlier API version. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) for collection in pc.collections.list(): print(collection.name, collection.status) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); const { collections = [] } = await pc.collections.list(); for (const collection of collections) { console.log(collection.name, collection.status); } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_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) } for _, collection := range collections { fmt.Println(collection.Name, collection.Status) } } ``` ```hcl Terraform theme={null} # Requires Terraform provider v5.0.0 or later data "pinecone_collections" "all" {} output "collections" { value = { for collection in coalesce(data.pinecone_collections.all.collections, []) : collection.name => collection.status } } ``` ```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-07" ``` # List conversion jobs Source: https://docs.pinecone.io/reference/api/2026-07/control-plane/list_conversion_jobs https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_control_2026-07.oas.yaml get /conversion-jobs List the project's conversion jobs, newest first. ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl "https://api.pinecone.io/conversion-jobs?limit=10" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" \ -H 'accept: application/json' ``` # List backups for an index Source: https://docs.pinecone.io/reference/api/2026-07/control-plane/list_index_backups https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_control_2026-07.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). ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) backups = pc.backups.list(index_name="docs-example") print(backups) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); const backups = await pc.backups.listByIndex('docs-example'); console.log(backups); ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } indexName := "docs-example" backups, err := pc.ListBackups(ctx, &pinecone.ListBackupsParams{ IndexName: &indexName, }) if err != nil { log.Fatalf("Failed to list backups: %v", err) } out, err := json.MarshalIndent(backups, "", " ") if err != nil { log.Fatalf("Failed to marshal response: %v", err) } fmt.Println(string(out)) } ``` ```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-07" \ -H "accept: application/json" ``` # List indexes Source: https://docs.pinecone.io/reference/api/2026-07/control-plane/list_indexes https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_control_2026-07.oas.yaml get /indexes List all indexes in a project. Returns all indexes in the project, including their current status and configuration. Each item in the response has the same shape as the response from [Describe an index](/reference/api/2026-07/control-plane/describe_index). ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) for index_model in pc.indexes.list(): print(index_model.name, index_model.host, index_model.status.state) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); const { indexes = [] } = await pc.indexes.list(); for (const indexModel of indexes) { console.log(indexModel.name, indexModel.host, indexModel.status.state); } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_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) } for _, idx := range idxs { fmt.Println(idx.Name, idx.Host, idx.Status.State) } } ``` ```hcl Terraform theme={null} # Requires Terraform provider v5.0.0 or later data "pinecone_indexes" "all" {} output "indexes" { value = { for index in coalesce(data.pinecone_indexes.all.indexes, []) : index.name => { host = index.host state = index.status.state } } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl "https://api.pinecone.io/indexes" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" ``` # List backups for all indexes in a project Source: https://docs.pinecone.io/reference/api/2026-07/control-plane/list_project_backups https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_control_2026-07.oas.yaml get /backups List all backups for a project. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) backups = pc.backups.list() print(backups) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); const backups = await pc.backups.list(); console.log(backups); ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } backups, err := pc.ListBackups(ctx, nil) if err != nil { log.Fatalf("Failed to list backups: %v", err) } out, err := json.MarshalIndent(backups, "", " ") if err != nil { log.Fatalf("Failed to marshal response: %v", err) } fmt.Println(string(out)) } ``` ```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-07" \ -H "accept: application/json" ``` # List restore jobs Source: https://docs.pinecone.io/reference/api/2026-07/control-plane/list_restore_jobs https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_control_2026-07.oas.yaml get /restore-jobs List all restore jobs for a project. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) restore_jobs = pc.restore_jobs.list() print(restore_jobs) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); const restoreJobs = await pc.restoreJobs.list(); console.log(restoreJobs); ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } restoreJobs, err := pc.ListRestoreJobs(ctx, nil) if err != nil { log.Fatalf("Failed to list restore jobs: %v", err) } out, err := json.MarshalIndent(restoreJobs, "", " ") if err != nil { log.Fatalf("Failed to marshal response: %v", err) } fmt.Println(string(out)) } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl "https://api.pinecone.io/restore-jobs" \ -H "X-Pinecone-Api-Version: 2026-07" \ -H "Api-Key: $PINECONE_API_KEY" ``` # Update backup schedule Source: https://docs.pinecone.io/reference/api/2026-07/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. > [!NOTE] > > This endpoint requires `X-Pinecone-Api-Version: 2026-07`. Update a backup schedule. Send only the fields you want to change. All body fields are optional. ### Path parameters **schedule_id** `string` *required* The ID of the backup schedule to update. ### Body parameters **enabled** `boolean` Whether the schedule is enabled. Set to `false` to pause the schedule without deleting it. **frequency** `string` How often backups are created. One of `daily`, `weekly`, or `monthly`. **retention** `object` The retention policy for backups created by this schedule. **retention properties** **expire_after_days** `integer` The number of days after which backups created by this schedule are automatically deleted. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) schedule = pc.backup_schedules.update( schedule_id="SCHEDULE_ID", enabled=False, frequency="weekly", retention_days=14, ) print(schedule) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); const schedule = await pc.backupSchedules.update('SCHEDULE_ID', { enabled: false, frequency: 'weekly', retentionDays: 14, }); console.log(schedule); ``` ```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: 2026-07" \ -H "Content-Type: application/json" \ -d '{ "enabled": false, "frequency": "weekly", "retention": { "expire_after_days": 14 } }' ``` # Cancel an import Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/cancel_import https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.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). > [!NOTE] > > This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) # To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index index = pc.index(host="INDEX_HOST") index.cancel_import("101") ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST' }); await index.cancelImport('101'); ``` ```go Go theme={null} package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection: %v", err) } err = idxConnection.CancelImport(ctx, "101") if err != nil { log.Fatalf("Failed to cancel import: %v", err) } } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/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-07" ``` # Create a namespace alias Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/create_namespace_alias https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.oas.yaml post /namespace-aliases Create an alias that resolves to an existing namespace in the index. Reads through the alias are served from its target namespace; writes to an alias name are rejected. Many aliases can resolve to the same namespace. The call returns once the alias resolves on every reader, which takes about a second; size client timeouts accordingly. A 409 whose `details.metadata.target_namespace` matches the requested target carries the same guarantee: your earlier call committed and the alias is live. For guidance and examples, see [Manage namespace aliases](https://docs.pinecone.io/guides/manage-data/namespace-aliases/manage-aliases). ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X POST "https://$INDEX_HOST/namespace-aliases" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "name": "dataset", "target_namespace": "dataset_v1" }' ``` # Create a namespace Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/createnamespace https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.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. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) # To get the host for an index, see https://docs.pinecone.io/guides/indexes/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} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index const index = pc.index({ host: '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); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection: %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.Println(namespace.Name, namespace.RecordCount) } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/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-07" \ -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} } } }' ``` # Delete records Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/delete https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.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). ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) # To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index index = pc.index(host="INDEX_HOST") index.delete(ids=["id-1", "id-2"], namespace="example-namespace") ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST', namespace: 'example-namespace', }); await index.deleteMany({ ids: ['id-1', 'id-2'], }); ``` ```go Go theme={null} package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{ Host: "INDEX_HOST", Namespace: "example-namespace", }) if err != nil { log.Fatalf("Failed to create IndexConnection: %v", err) } err = idxConnection.DeleteVectorsById(ctx, []string{"id-1", "id-2"}) if err != nil { log.Fatalf("Failed to delete vectors: %v", err) } } ``` ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/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-07" \ -d '{ "ids": [ "id-1", "id-2" ], "namespace": "example-namespace" } ' ``` # Delete documents Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/delete_documents https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.oas.yaml post /namespaces/{namespace}/documents/delete Delete documents from a namespace. Exactly one of `ids`, `filter`, or `delete_all` must be specified. - `ids`: Delete documents with the given IDs. - `filter`: Delete every document matching a metadata filter expression. Text-match operators (`$match_phrase`, `$match_all`, `$match_any`) are not supported in a filtered delete; they are only supported in search. The response reports `matched_records`, the number of documents the filter matched. - `delete_all`: Delete all documents in the namespace. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) index = pc.index(name="articles") NAMESPACE = "example-namespace" # Delete by IDs index.documents.delete(namespace=NAMESPACE, ids=["doc1", "doc2"]) # Delete by metadata filter index.documents.delete(namespace=NAMESPACE, filter={"category": {"$eq": "news"}}) # Delete every document in the namespace index.documents.delete(namespace=NAMESPACE, delete_all=True) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); const index = pc.index({ name: 'articles', namespace: 'example-namespace', }); // Delete by IDs await index.documents.delete({ ids: ['doc1', 'doc2'], }); // Delete by metadata filter const response = await index.documents.delete({ filter: { category: { $eq: 'news', }, }, }); console.log(`Matched ${response.matchedRecords} documents`); // Delete every document in the namespace await index.documents.delete({ deleteAll: true, }); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.DescribeIndex(ctx, "articles") if err != nil { log.Fatalf("Failed to describe index: %v", err) } idxConnection, err := pc.Index(pinecone.NewIndexConnParams{ Host: idx.Host, Namespace: "example-namespace", }) if err != nil { log.Fatalf("Failed to create IndexConnection: %v", err) } // Delete by IDs _, err = idxConnection.DeleteDocuments(ctx, &pinecone.DeleteDocumentsRequest{ Ids: []string{"doc1", "doc2"}, }) if err != nil { log.Fatalf("Failed to delete documents: %v", err) } // Delete by metadata filter res, err := idxConnection.DeleteDocuments(ctx, &pinecone.DeleteDocumentsRequest{ Filter: map[string]interface{}{ "category": map[string]interface{}{ "$eq": "news", }, }, }) if err != nil { log.Fatalf("Failed to delete documents: %v", err) } if res.MatchedRecords != nil { fmt.Printf("Matched %d documents\n", *res.MatchedRecords) } // Delete every document in the namespace _, err = idxConnection.DeleteDocuments(ctx, &pinecone.DeleteDocumentsRequest{ DeleteAll: true, }) if err != nil { log.Fatalf("Failed to delete documents: %v", err) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="articles-abc123.svc.us-east-1.pinecone.io" # EXAMPLE REQUEST 1: Delete by IDs curl "https://$INDEX_HOST/namespaces/__default__/documents/delete" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "ids": ["doc1", "doc2"] }' # EXAMPLE REQUEST 2: Delete by metadata filter curl "https://$INDEX_HOST/namespaces/__default__/documents/delete" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "filter": { "category": { "$eq": "news" } } }' # EXAMPLE REQUEST 3: Delete all documents in a namespace curl "https://$INDEX_HOST/namespaces/__default__/documents/delete" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "delete_all": true }' ``` # Delete a namespace alias Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/delete_namespace_alias https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.oas.yaml delete /namespace-aliases/{alias_name} Remove an alias. The target namespace and its data are unchanged. Reads that still use the alias name are treated as reads of a nonexistent namespace (empty results, not an error), so migrate readers off the alias first. The call returns once no reader still resolves the alias, which takes about a second; size client timeouts accordingly. A retried delete that returns 404 means the alias is already gone and carries the same guarantee. For guidance and examples, see [Manage namespace aliases](https://docs.pinecone.io/guides/manage-data/namespace-aliases/manage-aliases). ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" ALIAS_NAME="dataset" curl -X DELETE "https://$INDEX_HOST/namespace-aliases/$ALIAS_NAME" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" ``` # Delete a namespace Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/deletenamespace https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.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. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) # To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index index = pc.index(host="INDEX_HOST") index.delete_namespace(name="example-namespace") ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST' }); await index.deleteNamespace('example-namespace'); ``` ```go Go theme={null} package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection: %v", err) } err = idxConnection.DeleteNamespace(ctx, "example-namespace") if err != nil { log.Fatalf("Failed to delete namespace: %v", err) } } ``` ```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-07" ``` # Describe an import Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/describe_import https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.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). > [!NOTE] > > This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) # To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index index = pc.index(host="INDEX_HOST") import_op = index.describe_import("101") print(import_op.status, import_op.percent_complete, import_op.records_imported) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST' }); const importOp = await index.describeImport('101'); console.log(importOp.status, importOp.percentComplete, importOp.recordsImported); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection: %v", err) } importOp, err := idxConnection.DescribeImport(ctx, "101") if err != nil { log.Fatalf("Failed to describe import: %v", err) } fmt.Println(importOp.Status, importOp.PercentComplete, importOp.RecordsImported) } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/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-07' ``` # Describe a namespace alias Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/describe_namespace_alias https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.oas.yaml get /namespace-aliases/{alias_name} Get an alias and the namespace it resolves to. For guidance and examples, see [Manage namespace aliases](https://docs.pinecone.io/guides/manage-data/namespace-aliases/manage-aliases). ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" ALIAS_NAME="dataset" curl "https://$INDEX_HOST/namespace-aliases/$ALIAS_NAME" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" ``` # Get index stats Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/describeindexstats https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.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. > [!NOTE] > > Index fullness is also relevant for [dedicated read nodes](/guides/optimize/dedicated-read-nodes/concepts#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, these values indicate when the index needs more capacity. See [Scale your index](/guides/optimize/dedicated-read-nodes/scale). ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) # To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index index = pc.index(host="INDEX_HOST") stats = index.describe_index_stats() print(stats.total_vector_count) for name, summary in stats.namespaces.items(): print(name, summary.vector_count) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST' }); const stats = await index.describeIndexStats(); console.log(stats.totalRecordCount); for (const [name, summary] of Object.entries(stats.namespaces ?? {})) { console.log(name, summary.recordCount); } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{ Host: "INDEX_HOST", }) if err != nil { log.Fatalf("Failed to create IndexConnection: %v", err) } stats, err := idxConnection.DescribeIndexStats(ctx) if err != nil { log.Fatalf("Failed to describe index stats: %v", err) } fmt.Println(stats.TotalVectorCount) for name, summary := range stats.Namespaces { fmt.Println(name, summary.VectorCount) } } ``` ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/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-07" ``` # Describe a namespace Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/describenamespace https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.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. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) # To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index index = pc.index(host="INDEX_HOST") namespace = index.describe_namespace(name="example-namespace") print(namespace) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST' }); const namespace = await index.describeNamespace('example-namespace'); console.log(namespace); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection: %v", err) } namespace, err := idxConnection.DescribeNamespace(ctx, "example-namespace") if err != nil { log.Fatalf("Failed to describe namespace: %v", err) } fmt.Println(namespace.Name, namespace.RecordCount) } ``` ```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-07" ``` # Fetch records Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/fetch https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.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). ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) # To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index index = pc.index(host="INDEX_HOST") response = index.fetch(ids=["id-1", "id-2"], namespace="example-namespace") for vector_id, vector in response.vectors.items(): print(vector_id, vector.values) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST', namespace: 'example-namespace', }); const response = await index.fetch({ ids: ['id-1', 'id-2'], }); for (const [id, record] of Object.entries(response.records)) { console.log(id, record.values); } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{ Host: "INDEX_HOST", Namespace: "example-namespace", }) if err != nil { log.Fatalf("Failed to create IndexConnection: %v", err) } res, err := idxConnection.FetchVectors(ctx, []string{"id-1", "id-2"}) if err != nil { log.Fatalf("Failed to fetch vectors: %v", err) } for id, vector := range res.Vectors { fmt.Println(id, *vector.Values) } } ``` ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/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-07" ``` # Fetch records by metadata Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/fetch_by_metadata https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.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). ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) # To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index index = pc.index(host="INDEX_HOST") response = index.fetch_by_metadata( namespace="__default__", filter={"genre": {"$eq": "Action/Adventure"}}, limit=2, ) for vector_id, vector in response.vectors.items(): print(vector_id, vector.metadata) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST', namespace: '__default__', }); const response = await index.fetchByMetadata({ filter: { genre: { $eq: 'Action/Adventure' }, }, limit: 2, }); for (const [id, record] of Object.entries(response.records)) { console.log(id, record.metadata); } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{ Host: "INDEX_HOST", Namespace: "__default__", }) if err != nil { log.Fatalf("Failed to create IndexConnection: %v", err) } filter, err := pinecone.NewMetadataFilter(map[string]interface{}{ "genre": map[string]interface{}{ "$eq": "Action/Adventure", }, }) if err != nil { log.Fatalf("Failed to create metadata filter: %v", err) } limit := uint32(2) res, err := idxConnection.FetchVectorsByMetadata(ctx, &pinecone.FetchVectorsByMetadataRequest{ Filter: filter, Limit: &limit, }) if err != nil { log.Fatalf("Failed to fetch vectors by metadata: %v", err) } for id, vector := range res.Vectors { fmt.Println(id, vector.Metadata.AsMap()) } } ``` ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/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-07" \ -d '{ "namespace": "__default__", "filter": {"genre": {"$eq": "Action/Adventure"}}, "limit": 2 }' ``` # Fetch documents Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/fetch_documents https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.oas.yaml post /namespaces/{namespace}/documents/fetch Fetch documents from a namespace. Returns the specified fields for each document. Exactly one of `ids` or `filter` must be specified. - `ids`: Fetch the documents with the given IDs. - `filter`: Fetch every document matching a metadata filter expression. Results are returned a page at a time, holding `limit` documents per page (100 by default, 10000 at most). When there are more documents to return, the response includes a `pagination` token you can pass back as `pagination_token` to retrieve the next page. When no `pagination` token is returned, there are no more documents to fetch. > [!NOTE] > > Text-match operators (`$match_phrase`, `$match_all`, `$match_any`) are supported in a filtered fetch, as they are in [search](/reference/api/2026-07/data-plane/search_documents). A filtered [update](/reference/api/2026-07/data-plane/update_documents) or [delete](/reference/api/2026-07/data-plane/delete_documents) rejects them with a `400`. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) index = pc.index(name="articles") NAMESPACE = "example-namespace" # Fetch by IDs 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", "")) # Fetch by metadata filter, paging through all matches pagination_token = None while True: response = index.documents.fetch( namespace=NAMESPACE, filter={"category": {"$eq": "news"}}, include_fields=["title", "body", "category"], pagination_token=pagination_token, ) for doc_id, doc in response.documents.items(): print(doc_id, getattr(doc, "title", "")) pagination = getattr(response, "pagination", None) if not pagination or not getattr(pagination, "next", None): break pagination_token = pagination.next ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); const index = pc.index({ name: 'articles', namespace: 'example-namespace', }); // Fetch by IDs const response = await index.documents.fetch({ ids: ['doc1', 'doc2'], includeFields: ['title', 'body', 'category'], }); for (const [id, doc] of Object.entries(response.documents)) { console.log(id, doc.title); } // Fetch by metadata filter, paging through all matches let paginationToken; do { const page = await index.documents.fetch({ filter: { category: { $eq: 'news', }, }, includeFields: ['title', 'body', 'category'], paginationToken, }); for (const [id, doc] of Object.entries(page.documents)) { console.log(id, doc.title); } paginationToken = page.pagination?.next; } while (paginationToken); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.DescribeIndex(ctx, "articles") if err != nil { log.Fatalf("Failed to describe index: %v", err) } idxConnection, err := pc.Index(pinecone.NewIndexConnParams{ Host: idx.Host, Namespace: "example-namespace", }) if err != nil { log.Fatalf("Failed to create IndexConnection: %v", err) } // Fetch by IDs res, err := idxConnection.FetchDocuments(ctx, &pinecone.FetchDocumentsRequest{ Ids: []string{"doc1", "doc2"}, IncludeFields: []string{"title", "body", "category"}, }) if err != nil { log.Fatalf("Failed to fetch documents: %v", err) } for id, doc := range res.Documents { fmt.Println(id, doc["title"]) } // Fetch by metadata filter, paging through all matches var paginationToken *string for { res, err := idxConnection.FetchDocuments(ctx, &pinecone.FetchDocumentsRequest{ Filter: map[string]interface{}{ "category": map[string]interface{}{ "$eq": "news", }, }, IncludeFields: []string{"title", "body", "category"}, PaginationToken: paginationToken, }) if err != nil { log.Fatalf("Failed to fetch documents: %v", err) } for id, doc := range res.Documents { fmt.Println(id, doc["title"]) } if res.Pagination == nil || res.Pagination.Next == "" { break } paginationToken = &res.Pagination.Next } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="articles-abc123.svc.us-east-1.pinecone.io" # EXAMPLE REQUEST 1: Fetch by IDs curl "https://$INDEX_HOST/namespaces/__default__/documents/fetch" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "ids": ["doc1", "doc2"], "include_fields": ["title", "body", "category"] }' # EXAMPLE REQUEST 2: Fetch by metadata filter curl "https://$INDEX_HOST/namespaces/__default__/documents/fetch" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "filter": { "category": { "$eq": "news" } }, "include_fields": ["title", "body", "category"] }' ``` # List record IDs Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/list https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.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 includes `pagination.next`, a token you pass as `paginationToken` to get the next batch of IDs. When the response has no `pagination`, 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. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) # To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index index = pc.index(host="INDEX_HOST") for page in index.list(prefix="doc1#", limit=3, namespace="example-namespace"): print([item.id for item in page.vectors]) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST', namespace: 'example-namespace', }); let paginationToken; do { const page = await index.listPaginated({ prefix: 'doc1#', limit: 3, paginationToken, }); for (const vector of page.vectors ?? []) { console.log(vector.id); } paginationToken = page.pagination?.next; } while (paginationToken); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{ Host: "INDEX_HOST", Namespace: "example-namespace", }) if err != nil { log.Fatalf("Failed to create IndexConnection: %v", err) } prefix := "doc1#" limit := uint32(3) var paginationToken *string for { res, err := idxConnection.ListVectors(ctx, &pinecone.ListVectorsRequest{ Prefix: &prefix, Limit: &limit, PaginationToken: paginationToken, }) if err != nil { log.Fatalf("Failed to list vectors: %v", err) } for _, id := range res.VectorIds { fmt.Println(*id) } if res.NextPaginationToken == nil { break } paginationToken = res.NextPaginationToken } } ``` ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/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%23&limit=3" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" ``` # List documents Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/list_documents https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.oas.yaml post /namespaces/{namespace}/documents/list List documents in a namespace. Returns up to 100 documents per page by default, in sorted order (bitwise "C" collation). Use the optional `prefix` parameter to limit results to documents whose IDs start with a given prefix. When there are more documents to return, the response includes a `pagination` token you can pass to retrieve the next page. When no `pagination` token is returned, there are no more documents to list. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) index = pc.index(name="articles") NAMESPACE = "example-namespace" # List every document ID in the namespace. # The SDK returns a paginator, so iterating it walks every page. for document in index.documents.list(namespace=NAMESPACE): print(document.id) # List only the IDs beginning with a prefix. for document in index.documents.list(namespace=NAMESPACE, prefix="report-2026#"): print(document.id) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); const index = pc.index({ name: 'articles', namespace: 'example-namespace', }); // List every document ID in the namespace. // Each response holds one page, so pass the pagination token to walk every page. let paginationToken; do { const page = await index.documents.list({ paginationToken, }); for (const doc of page.documents) { console.log(doc._id); } paginationToken = page.pagination?.next; } while (paginationToken); // List only the IDs beginning with a prefix. const response = await index.documents.list({ prefix: 'report-2026#', }); for (const doc of response.documents) { console.log(doc._id); } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.DescribeIndex(ctx, "articles") if err != nil { log.Fatalf("Failed to describe index: %v", err) } idxConnection, err := pc.Index(pinecone.NewIndexConnParams{ Host: idx.Host, Namespace: "example-namespace", }) if err != nil { log.Fatalf("Failed to create IndexConnection: %v", err) } // List every document ID in the namespace. // Each response holds one page, so pass the pagination token to walk every page. var paginationToken *string for { res, err := idxConnection.ListDocuments(ctx, &pinecone.ListDocumentsRequest{ PaginationToken: paginationToken, }) if err != nil { log.Fatalf("Failed to list documents: %v", err) } for _, doc := range res.Documents { fmt.Println(doc.Id) } if res.Pagination == nil || res.Pagination.Next == "" { break } paginationToken = &res.Pagination.Next } // List only the IDs beginning with a prefix. prefix := "report-2026#" res, err := idxConnection.ListDocuments(ctx, &pinecone.ListDocumentsRequest{ Prefix: &prefix, }) if err != nil { log.Fatalf("Failed to list documents: %v", err) } for _, doc := range res.Documents { fmt.Println(doc.Id) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="articles-abc123.svc.us-east-1.pinecone.io" # EXAMPLE REQUEST 1: List the first page of document IDs curl "https://$INDEX_HOST/namespaces/__default__/documents/list" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "limit": 20 }' # EXAMPLE REQUEST 2: List only the IDs beginning with a prefix curl "https://$INDEX_HOST/namespaces/__default__/documents/list" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "prefix": "report-2026#" }' # EXAMPLE REQUEST 3: Retrieve the next page curl "https://$INDEX_HOST/namespaces/__default__/documents/list" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "pagination_token": "Tm90aGluZyB0byBzZWUgaGVyZQo=" }' ``` # List imports Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/list_imports https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.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_imports` returns up to that number of imports instead. Whenever there are additional imports to return, the response includes `pagination.next`, a token you pass as `paginationToken` to get the next batch of imports. When the response has no `pagination`, there are no more imports to return. For guidance and examples, see [Import data](https://docs.pinecone.io/guides/index-data/import-data). > [!NOTE] > > This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) # To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index index = pc.index(host="INDEX_HOST") for import_op in index.list_imports(limit=10): print(import_op.id, import_op.status) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST' }); let paginationToken; do { const page = await index.listImports(10, paginationToken); for (const importOp of page.data ?? []) { console.log(importOp.id, importOp.status); } paginationToken = page.pagination?.next; } while (paginationToken); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection: %v", err) } limit := int32(10) var paginationToken *string for { res, err := idxConnection.ListImports(ctx, &pinecone.ListImportsRequest{ Limit: &limit, PaginationToken: paginationToken, }) if err != nil { log.Fatalf("Failed to list imports: %v", err) } for _, importOp := range res.Imports { fmt.Println(importOp.Id, importOp.Status) } if res.NextPaginationToken == nil { break } paginationToken = res.NextPaginationToken } } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/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-07' ``` # List namespace aliases Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/list_namespace_aliases https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.oas.yaml get /namespace-aliases List the namespace aliases in a serverless index, ordered by name. Filter by name prefix or by target namespace. Up to 100 aliases are returned per page; set `limit` to return fewer. When more remain, the response includes `pagination.next`; pass it as `paginationToken` to get the next page. For guidance and examples, see [Manage namespace aliases](https://docs.pinecone.io/guides/manage-data/namespace-aliases/manage-aliases). ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/namespace-aliases" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2026-07" ``` # List namespaces Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/listnamespaces https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.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 includes `pagination.next`, a token you pass as `paginationToken` to get the next batch of namespaces. When the response has no `pagination`, 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. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) # To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index index = pc.index(host="INDEX_HOST") for page in index.list_namespaces(): for namespace in page.namespaces: print(namespace.name, namespace.record_count) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST' }); let paginationToken; do { const page = await index.listNamespaces({ paginationToken }); for (const namespace of page.namespaces ?? []) { console.log(namespace.name, namespace.recordCount); } paginationToken = page.pagination?.next; } while (paginationToken); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection: %v", err) } var paginationToken *string for { res, err := idxConnection.ListNamespaces(ctx, &pinecone.ListNamespacesParams{ PaginationToken: paginationToken, }) if err != nil { log.Fatalf("Failed to list namespaces: %v", err) } for _, namespace := range res.Namespaces { fmt.Println(namespace.Name, namespace.RecordCount) } if res.Pagination == nil || res.Pagination.Next == "" { break } paginationToken = &res.Pagination.Next } } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/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-07" ``` # Search with a vector Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/query https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.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). ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) # To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index index = pc.index(host="INDEX_HOST") response = index.query( namespace="example-namespace", vector=[0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3], filter={"genre": {"$eq": "documentary"}}, top_k=3, include_values=True, ) for match in response.matches: print(match.id, match.score, match.values) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST', namespace: 'example-namespace', }); const response = await index.query({ 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, }); for (const match of response.matches) { console.log(match.id, match.score, match.values); } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{ Host: "INDEX_HOST", Namespace: "example-namespace", }) if err != nil { log.Fatalf("Failed to create IndexConnection: %v", err) } filter, err := pinecone.NewMetadataFilter(map[string]interface{}{ "genre": map[string]interface{}{ "$eq": "documentary", }, }) if err != nil { log.Fatalf("Failed to create metadata filter: %v", err) } res, err := idxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{ Vector: []float32{0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3}, TopK: 3, MetadataFilter: filter, IncludeValues: true, }) if err != nil { log.Fatalf("Failed to query vectors: %v", err) } for _, match := range res.Matches { fmt.Println(match.Vector.Id, match.Score, *match.Vector.Values) } } ``` ```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-07" \ -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 }' ``` # Repoint a namespace alias Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/repoint_namespace_alias https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.oas.yaml patch /namespace-aliases/{alias_name} Update the namespace an alias resolves to. The change is atomic: the target is validated in the same transaction that rewrites the alias, and on failure the alias keeps its current target. The call returns once the new target is live on every reader, which takes about a second; size client timeouts accordingly. Reads through the alias that start after the response are served from the new namespace, so no polling is needed. Repointing is safe to retry; `updated_at` advances on every attempt. For guidance and examples, see [Manage namespace aliases](https://docs.pinecone.io/guides/manage-data/namespace-aliases/manage-aliases). ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" ALIAS_NAME="dataset" curl -X PATCH "https://$INDEX_HOST/namespace-aliases/$ALIAS_NAME" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "target_namespace": "dataset_v2" }' ``` # Search documents Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/search_documents https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.oas.yaml post /namespaces/{namespace}/documents/search Search for documents in a namespace using one or more scoring methods (dense vector, sparse vector, text, or query string similarity, or similarity to query text that Pinecone embeds with a field's own model). Returns the top-k most similar documents along with their scores and requested fields. Filters apply before scoring, so only documents that match the `filter` are ranked. For how each scoring type works and how to combine them, see [Full-text search](/guides/search/full-text-search) and the [query syntax reference](/guides/search/full-text-search/query-syntax). ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) index = pc.index(name="articles") NAMESPACE = "example-namespace" # BM25 token matching response = index.documents.search( namespace=NAMESPACE, top_k=10, score_by=[{"type": "text", "fields": ["body"], "query": "machine learning"}], include_fields=["title", "body", "category", "year"], ) for match in response.matches: print(match.id, match.score, getattr(match, "title", "")) # Lucene query string 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"], ) # Dense vector ranking with phrase-match filter query_vector = [0.12, 0.34, 0.56] # replace with your actual query vector response = index.documents.search( namespace=NAMESPACE, top_k=10, score_by=[{ "type": "dense_vector", "fields": ["embedding"], "values": query_vector, }], filter={"body": {"$match_phrase": "machine learning"}}, include_fields=["title", "body"], ) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); const index = pc.index({ name: 'articles', namespace: 'example-namespace', }); // BM25 token matching let response = await index.documents.search({ topK: 10, scoreBy: [ { type: 'text', fields: ['body'], query: 'machine learning', }, ], includeFields: ['title', 'body', 'category', 'year'], }); for (const match of response.matches) { console.log(match._id, match._score, match.title); } // Lucene query string response = await index.documents.search({ topK: 10, scoreBy: [ { type: 'query_string', query: 'title:(quantum) OR body:(machine learning)', }, ], includeFields: ['title', 'body'], }); // Dense vector ranking with phrase-match filter const queryVector = [0.12, 0.34, 0.56]; // replace with your actual query vector response = await index.documents.search({ topK: 10, scoreBy: [ { type: 'dense_vector', fields: ['embedding'], values: queryVector, }, ], filter: { body: { $match_phrase: 'machine learning', }, }, includeFields: ['title', 'body'], }); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.DescribeIndex(ctx, "articles") if err != nil { log.Fatalf("Failed to describe index: %v", err) } idxConnection, err := pc.Index(pinecone.NewIndexConnParams{ Host: idx.Host, Namespace: "example-namespace", }) if err != nil { log.Fatalf("Failed to create IndexConnection: %v", err) } // BM25 token matching textQuery := "machine learning" res, err := idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{ TopK: 10, ScoreBy: []pinecone.DocumentScoringMethod{ { Type: "text", Fields: []string{"body"}, Query: &textQuery, }, }, IncludeFields: []string{"title", "body", "category", "year"}, }) if err != nil { log.Fatalf("Failed to search documents: %v", err) } for _, match := range res.Matches { fmt.Print(match.Id) if match.Score != nil { fmt.Printf(" %.3f", *match.Score) } fmt.Printf(" %v\n", match.Fields["title"]) } // Lucene query string queryString := "title:(quantum) OR body:(machine learning)" res, err = idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{ TopK: 10, ScoreBy: []pinecone.DocumentScoringMethod{ { Type: "query_string", Query: &queryString, }, }, IncludeFields: []string{"title", "body"}, }) if err != nil { log.Fatalf("Failed to search documents: %v", err) } // Dense vector ranking with phrase-match filter queryVector := []float32{0.12, 0.34, 0.56} // replace with your actual query vector res, err = idxConnection.SearchDocuments(ctx, &pinecone.SearchDocumentsRequest{ TopK: 10, ScoreBy: []pinecone.DocumentScoringMethod{ { Type: "dense_vector", Fields: []string{"embedding"}, Values: &queryVector, }, }, Filter: map[string]interface{}{ "body": map[string]interface{}{ "$match_phrase": "machine learning", }, }, IncludeFields: []string{"title", "body"}, }) if err != nil { log.Fatalf("Failed to search documents: %v", err) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="articles-abc123.svc.us-east-1.pinecone.io" # EXAMPLE REQUEST 1: BM25 token matching (type: "text") curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "include_fields": ["title", "body", "category", "year"], "score_by": [{ "type": "text", "fields": ["body"], "query": "machine learning" }], "top_k": 10 }' # EXAMPLE REQUEST 2: Cross-field boolean query (type: "query_string") curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "include_fields": ["title", "body"], "score_by": [{ "type": "query_string", "query": "title:(quantum) OR body:(machine learning)" }], "top_k": 10 }' # EXAMPLE REQUEST 3: Dense vector ranking with phrase-match filter curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "include_fields": ["title", "body"], "filter": { "body": { "$match_phrase": "machine learning" } }, "score_by": [{ "type": "dense_vector", "fields": ["embedding"], "values": [0.12, 0.34, 0.56] }], "top_k": 10 }' # EXAMPLE REQUEST 4: Sparse vector ranking curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "include_fields": ["title", "body"], "score_by": [{ "type": "sparse_vector", "fields": ["sparse_embedding"], "sparse_values": { "indices": [12, 287, 4096], "values": [0.41, 0.33, 0.18] } }], "top_k": 10 }' # EXAMPLE REQUEST 5: Compound filter ($and + $match_all + metadata) curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "include_fields": ["body", "category", "year"], "filter": { "$and": [ { "body": { "$match_all": "federal reserve" } }, { "category": { "$eq": "finance" } }, { "year": { "$gte": 2024 } } ] }, "score_by": [{ "type": "text", "fields": ["body"], "query": "monetary policy impact" }], "top_k": 10 }' ``` # Search with text (legacy Records API) Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/search_records https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.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. This operation is part of the legacy Records API, which legacy integrated indexes require. For new work, create a document index with a `string` field that uses integrated embedding (`embed` or `sparse_embed`), and search it with the Documents API's `search_documents` operation and an `embed` or `sparse_embed` scoring method. Searching with text (`inputs`) is supported only for [legacy integrated indexes](https://docs.pinecone.io/guides/index-data/indexing-overview#vector-embedding); for any other index a text query is rejected with `400`, and it is not available on BYOC indexes; reranking (`rerank`) is likewise unavailable on BYOC indexes. Searching with a query vector (`vector`) or a record ID (`id`) works on any index served by the vectors API. For guidance and examples, see [Search](https://docs.pinecone.io/guides/search/search-overview). ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) # To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index index = pc.index(host="INDEX_HOST") # Search with a query text and rerank the results # Supported only for indexes with integrated embedding search_with_text = index.search( namespace="example-namespace", inputs={"text": "Disease prevention"}, top_k=4, fields=["category", "chunk_text"], rerank={ "model": "bge-reranker-v2-m3", "top_n": 2, "rank_fields": ["chunk_text"], }, ) for hit in search_with_text.result.hits: print(hit.id, hit.score, hit.fields) # Search with a query vector and rerank the results search_with_vector = index.search( namespace="example-namespace", vector=[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"], }, ) for hit in search_with_vector.result.hits: print(hit.id, hit.score, hit.fields) # Search with a record ID and rerank the results search_with_id = index.search( namespace="example-namespace", 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"], }, ) for hit in search_with_id.result.hits: print(hit.id, hit.score, hit.fields) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST', namespace: 'example-namespace', }); // Search with a query text and rerank the results // Supported only for indexes with integrated embedding const searchWithText = await index.searchRecords({ query: { inputs: { text: 'Disease prevention' }, topK: 4, }, fields: ['category', 'chunk_text'], rerank: { model: 'bge-reranker-v2-m3', topN: 2, rankFields: ['chunk_text'], }, }); console.log(searchWithText.result.hits); // Search with a query vector and rerank the results const searchWithVector = await index.searchRecords({ query: { vector: { values: [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3], }, topK: 4, }, fields: ['category', 'chunk_text'], rerank: { query: 'Disease prevention', model: 'bge-reranker-v2-m3', topN: 2, rankFields: ['chunk_text'], }, }); console.log(searchWithVector.result.hits); // Search with a record ID and rerank the results const searchWithId = await index.searchRecords({ query: { id: 'rec1', topK: 4, }, fields: ['category', 'chunk_text'], rerank: { query: 'Disease prevention', model: 'bge-reranker-v2-m3', topN: 2, rankFields: ['chunk_text'], }, }); console.log(searchWithId.result.hits); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{ Host: "INDEX_HOST", Namespace: "example-namespace", }) if err != nil { log.Fatalf("Failed to create IndexConnection: %v", err) } fields := []string{"category", "chunk_text"} rerankQuery := "Disease prevention" topN := int32(2) // Search with a query text and rerank the results // Supported only for indexes with integrated embedding searchWithText, err := idxConnection.SearchRecords(ctx, &pinecone.SearchRecordsRequest{ Query: pinecone.SearchRecordsQuery{ Inputs: &map[string]interface{}{ "text": "Disease prevention", }, TopK: 4, }, Fields: &fields, Rerank: &pinecone.SearchRecordsRerank{ Model: "bge-reranker-v2-m3", TopN: &topN, RankFields: []string{"chunk_text"}, }, }) if err != nil { log.Fatalf("Failed to search with text: %v", err) } for _, hit := range searchWithText.Result.Hits { fmt.Println(hit.Id, hit.Score, hit.Fields["category"]) } // Search with a query vector and rerank the results searchWithVector, err := idxConnection.SearchRecords(ctx, &pinecone.SearchRecordsRequest{ Query: pinecone.SearchRecordsQuery{ Vector: &pinecone.SearchRecordsVector{ Values: &[]float32{0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3}, }, TopK: 4, }, Fields: &fields, Rerank: &pinecone.SearchRecordsRerank{ Query: &rerankQuery, Model: "bge-reranker-v2-m3", TopN: &topN, RankFields: []string{"chunk_text"}, }, }) if err != nil { log.Fatalf("Failed to search with vector: %v", err) } for _, hit := range searchWithVector.Result.Hits { fmt.Println(hit.Id, hit.Score, hit.Fields["category"]) } // Search with a record ID and rerank the results recordId := "rec1" searchWithId, err := idxConnection.SearchRecords(ctx, &pinecone.SearchRecordsRequest{ Query: pinecone.SearchRecordsQuery{ Id: &recordId, TopK: 4, }, Fields: &fields, Rerank: &pinecone.SearchRecordsRerank{ Query: &rerankQuery, Model: "bge-reranker-v2-m3", TopN: &topN, RankFields: []string{"chunk_text"}, }, }) if err != nil { log.Fatalf("Failed to search with ID: %v", err) } for _, hit := range searchWithId.Result.Hits { fmt.Println(hit.Id, hit.Score, hit.Fields["category"]) } } ``` ```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-07" \ -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"] } }' # 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-07" \ -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"] } }' # Search with a record ID 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-07" \ -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"] } }' ``` # Start import Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/start_import https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.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). > [!NOTE] > > This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) # To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index index = pc.index(host="INDEX_HOST") response = index.start_import( uri="s3://BUCKET_NAME/PATH/TO/DIR", error_mode="continue", integration_id="a12b3d4c-47d2-492c-a97a-dd98c8dbefde", ) print(response.id) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST' }); const response = await index.startImport({ uri: 's3://BUCKET_NAME/PATH/TO/DIR', errorMode: 'continue', integration: 'a12b3d4c-47d2-492c-a97a-dd98c8dbefde', }); console.log(response.id); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection: %v", err) } integrationId := "a12b3d4c-47d2-492c-a97a-dd98c8dbefde" errorMode := string(pinecone.ImportErrorModeContinue) res, err := idxConnection.StartImport(ctx, "s3://BUCKET_NAME/PATH/TO/DIR", &integrationId, &errorMode) if err != nil { log.Fatalf("Failed to start import: %v", err) } fmt.Println(res.Id) } ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/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-07' \ -d '{ "integrationId": "a12b3d4c-47d2-492c-a97a-dd98c8dbefde", "uri": "s3://BUCKET_NAME/PATH/TO/DIR", "errorMode": { "onError": "continue" } }' ``` # Update a record Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/update https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.oas.yaml post /vectors/update Update records in a namespace, either by ID or with a metadata filter. By ID, you can change a single record's vector values, its metadata, or both. A filter updates metadata only, and applies to every record that matches. 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). ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) # To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index index = pc.index(host="INDEX_HOST") index.update( id="id-3", values=[4.0, 2.0], set_metadata={"type": "comedy"}, namespace="example-namespace", ) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST', namespace: 'example-namespace', }); await index.update({ id: 'id-3', values: [4.0, 2.0], metadata: { type: 'comedy' }, }); ``` ```go Go theme={null} package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{ Host: "INDEX_HOST", Namespace: "example-namespace", }) if err != nil { log.Fatalf("Failed to create IndexConnection: %v", err) } metadata, err := pinecone.NewMetadata(map[string]interface{}{ "type": "comedy", }) if err != nil { log.Fatalf("Failed to create metadata: %v", err) } err = idxConnection.UpdateVector(ctx, &pinecone.UpdateVectorRequest{ Id: "id-3", Values: []float32{4.0, 2.0}, Metadata: metadata, }) if err != nil { log.Fatalf("Failed to update vector: %v", err) } } ``` ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/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-07" \ -d '{ "id": "id-3", "values": [4.0, 2.0], "setMetadata": {"type": "comedy"}, "namespace": "example-namespace" }' ``` # Update documents Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/update_documents https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.oas.yaml post /namespaces/{namespace}/documents/update Update documents in a namespace, either by ID with `documents` or in bulk with `filter`. You can't use both in one request. - `documents`: Each entry is identified by `_id`. Fields you set get new values, fields listed in `_remove_fields` are removed, and other fields don't change. - `filter`: Applies `set_fields` and/or `remove_fields` to every matching document. It can change only metadata fields. The response reports `matched_records`. Setting a field that declares `embed` or `sparse_embed` re-embeds its text. Every request that does this is metered, including retries, and the response reports the tokens used in `usage.embed_total_tokens`. An update to an `_id` that doesn't exist has no effect, but any text it sets is still embedded and metered. An index that embeds a field accepts at most 96 documents per request. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) index = pc.index(name="articles") NAMESPACE = "example-namespace" # Patch specific documents by ID index.documents.update( namespace=NAMESPACE, documents=[ {"_id": "doc1", "title": "Updated title"}, {"_id": "doc2", "_remove_fields": ["content"]}, ], ) # Apply the same patch to every document matching a metadata filter index.documents.update( namespace=NAMESPACE, filter={"category": {"$eq": "news"}}, set_fields={"category": "archive"}, remove_fields=["year"], ) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); const index = pc.index({ name: 'articles', namespace: 'example-namespace', }); // Patch specific documents by ID await index.documents.update({ documents: [ { _id: 'doc1', title: 'Updated title', }, { _id: 'doc2', _remove_fields: ['content'], // Reserved document key, sent as-is }, ], }); // Apply the same patch to every document matching a metadata filter const response = await index.documents.update({ filter: { category: { $eq: 'news', }, }, setFields: { category: 'archive', }, removeFields: ['year'], }); console.log(`Matched ${response.matchedRecords} documents`); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.DescribeIndex(ctx, "articles") if err != nil { log.Fatalf("Failed to describe index: %v", err) } idxConnection, err := pc.Index(pinecone.NewIndexConnParams{ Host: idx.Host, Namespace: "example-namespace", }) if err != nil { log.Fatalf("Failed to create IndexConnection: %v", err) } // Patch specific documents by ID _, err = idxConnection.UpdateDocuments(ctx, &pinecone.UpdateDocumentsRequest{ Documents: []pinecone.Document{ { "_id": "doc1", "title": "Updated title", }, { "_id": "doc2", "_remove_fields": []string{"content"}, }, }, }) if err != nil { log.Fatalf("Failed to update documents: %v", err) } // Apply the same patch to every document matching a metadata filter res, err := idxConnection.UpdateDocuments(ctx, &pinecone.UpdateDocumentsRequest{ Filter: map[string]interface{}{ "category": map[string]interface{}{ "$eq": "news", }, }, SetFields: map[string]interface{}{ "category": "archive", }, RemoveFields: []string{"year"}, }) if err != nil { log.Fatalf("Failed to update documents: %v", err) } if res.MatchedRecords != nil { fmt.Printf("Matched %d documents\n", *res.MatchedRecords) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="articles-abc123.svc.us-east-1.pinecone.io" # EXAMPLE REQUEST 1: Patch specific documents by ID curl "https://$INDEX_HOST/namespaces/__default__/documents/update" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "documents": [ { "_id": "doc1", "title": "Updated title" }, { "_id": "doc2", "_remove_fields": ["content"] } ] }' # EXAMPLE REQUEST 2: Update by metadata filter curl "https://$INDEX_HOST/namespaces/__default__/documents/update" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -d '{ "filter": { "category": { "$eq": "news" } }, "set_fields": { "category": "archive" }, "remove_fields": ["year"] }' ``` # Upsert records Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/upsert https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.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). > [!TIP] > > To control costs when ingesting large datasets (10,000,000+ records), use [import](/guides/data/import-data) instead of upsert. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) # To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index index = pc.index(host="INDEX_HOST") response = index.upsert( 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", ) print(response.upserted_count) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST', namespace: 'example-namespace', }); await index.upsert({ records: [ { 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 }, }, ], }); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{ Host: "INDEX_HOST", Namespace: "example-namespace", }) if err != nil { log.Fatalf("Failed to create IndexConnection: %v", err) } metadata1, err := pinecone.NewMetadata(map[string]interface{}{ "genre": "comedy", "year": 2020, }) if err != nil { log.Fatalf("Failed to create metadata: %v", err) } metadata2, err := pinecone.NewMetadata(map[string]interface{}{ "genre": "documentary", "year": 2019, }) if err != nil { log.Fatalf("Failed to create metadata: %v", err) } vectors := []*pinecone.Vector{ { Id: "vec1", Values: &[]float32{0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1}, Metadata: metadata1, }, { Id: "vec2", Values: &[]float32{0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2}, Metadata: metadata2, }, } count, err := idxConnection.UpsertVectors(ctx, vectors) if err != nil { log.Fatalf("Failed to upsert vectors: %v", err) } fmt.Printf("Upserted %d vectors\n", count) } ``` ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/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-07" \ -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 documents Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/upsert_documents https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.oas.yaml post /namespaces/{namespace}/documents/upsert Upsert documents into a namespace. Each document needs an `_id` and at least one field from the index schema. Fields not in the schema are stored as metadata and indexed for filtering. For a `string` field that declares `embed` or `sparse_embed`, send the text and Pinecone generates the vectors. A field with `embed` is required on every document. An index that embeds a field accepts at most 96 documents per request. Every request that embeds text is metered, including retries, and the response reports the tokens used in `usage.embed_total_tokens`. If embedding fails, nothing in the request is written. Documents with the same `_id` in one request are each written and billed, and the last one wins. Upsert fully replaces any document with the same `_id`, so fields you omit are removed. To change specific fields, use [Update documents](/reference/api/2026-07/data-plane/update_documents). If any document fails schema validation, the whole request fails and nothing is written. The namespace is created on first upsert (use `__default__` if you don't need partitioning), and documents become searchable within about a minute. ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) index = pc.index(name="articles") 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}, ] # For large ingests, index.documents.batch_upsert(...) splits documents into # concurrent requests to this endpoint. index.documents.upsert( namespace=NAMESPACE, documents=docs, ) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); const index = pc.index({ name: 'articles', namespace: 'example-namespace', }); const result = await index.documents.upsert({ 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, }, ], }); console.log(`Upserted ${result.upsertedCount} documents`); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.DescribeIndex(ctx, "articles") if err != nil { log.Fatalf("Failed to describe index: %v", err) } idxConnection, err := pc.Index(pinecone.NewIndexConnParams{ Host: idx.Host, Namespace: "example-namespace", }) if err != nil { log.Fatalf("Failed to create IndexConnection: %v", err) } res, err := idxConnection.UpsertDocuments(ctx, &pinecone.UpsertDocumentsRequest{ Documents: []pinecone.Document{ { "_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, }, }, }) if err != nil { log.Fatalf("Failed to upsert documents: %v", err) } fmt.Printf("Upserted %d documents\n", res.UpsertedCount) } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="articles-abc123.svc.us-east-1.pinecone.io" curl "https://$INDEX_HOST/namespaces/__default__/documents/upsert" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2026-07" \ -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 } ] }' ``` # Upsert text (legacy Records API) Source: https://docs.pinecone.io/reference/api/2026-07/data-plane/upsert_records https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.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. This operation is part of the legacy Records API, which legacy integrated indexes require. For new work, create a document index with a `string` field that uses integrated embedding (`embed` or `sparse_embed`), and write text with the Documents API's `upsert_documents` operation. Upserting text is supported only for [legacy integrated indexes](https://docs.pinecone.io/guides/index-data/create-an-index#embedding-models); for any other index the request is rejected with `400`. It is not available on BYOC indexes. A request can contain at most 1000 records. Each record is identified by `_id`. The service also accepts `id` as an alias, which this schema does not model; a record must not carry both. For guidance, examples, and limits, see [Upsert data](https://docs.pinecone.io/guides/index-data/upsert-data). ```python Python theme={null} # pip install --upgrade pinecone import os from pinecone import Pinecone pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"]) # To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index index = pc.index(host="INDEX_HOST") index.upsert_records( namespace="example-namespace", records=[ { "_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} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; // Reads PINECONE_API_KEY from the environment const pc = new Pinecone(); // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index const index = pc.index({ host: 'INDEX_HOST', namespace: 'example-namespace', }); await index.upsertRecords({ records: [ { _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', }, ], }); ``` ```go Go theme={null} package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v7/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: os.Getenv("PINECONE_API_KEY"), }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the host for an index, see https://docs.pinecone.io/guides/indexes/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{ Host: "INDEX_HOST", Namespace: "example-namespace", }) if err != nil { log.Fatalf("Failed to create IndexConnection: %v", err) } 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 records: %v", err) } } ``` ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/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-07" \ -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-07/inference/describe-a-model https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/inference_2026-07.oas.yaml get /models/{model_name} Get a description of a model hosted by Pinecone. You can use hosted models for integrated inference in Pinecone operations, such as integrated-embedding fields in a document index, 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). # Generate vectors Source: https://docs.pinecone.io/reference/api/2026-07/inference/generate-vectors https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/inference_2026-07.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). # List available models Source: https://docs.pinecone.io/reference/api/2026-07/inference/list-available-models https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/inference_2026-07.oas.yaml get /models List the embedding and reranking models hosted by Pinecone. You can use hosted models for integrated inference in Pinecone operations, such as integrated-embedding fields in a document index, 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). # Rerank results Source: https://docs.pinecone.io/reference/api/2026-07/inference/rerank-results https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/inference_2026-07.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). # Pinecone API 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](/admin/security/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; 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", "disabled", null); } } ``` ```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: 2026-07" \ -d '{ "name": "docs-example", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "_values": { "type": "dense_vector", "dimension": 1536, "metric": "cosine" } } } }' ``` ## Add headers to an HTTP request All HTTP requests to Pinecone APIs must contain an `Api-Key` header that specifies a valid [API key](/admin/security/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: 2026-07" \ -d '{ "name": "docs-example", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "_values": { "type": "dense_vector", "dimension": 1536, "metric": "cosine" } } } }' ``` ## Troubleshooting > [accordion] Initialization errors due to outdated SDKs > > 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 overview Source: https://docs.pinecone.io/reference/api/database-limits Reference for Pinecone Database rate, object, operation, and identifier limits, plus known index and serverless limitations. This page describes the limits and known limitations for Pinecone Database. Each topic has its own reference page: * **[Rate limits](/reference/api/database-limits/rate-limits)**: request-per-second, monthly usage, and model throughput limits that vary by pricing plan, plus the `429` errors you get when you exceed them. * **[Object limits](/reference/api/database-limits/object-limits)**: the number or size of projects, users, indexes, namespaces, storage, backups, and collections allowed by plan. * **[Operation limits](/reference/api/database-limits/operation-limits)**: fixed batch-size limits for upsert, import, query, fetch, and delete, plus metadata filter limits. * **[Identifier limits](/reference/api/database-limits/identifier-limits)**: maximum length and allowed characters for organization, project, index, namespace, and record identifiers. * **[Known limitations](/reference/api/known-limitations)**: index and serverless caveats, such as upsert consistency and metadata rules. > [!NOTE] > > If a limit is blocking you, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. Many limits can be raised on request, and Support can often suggest a workaround for the ones that can't. # Identifier limits Source: https://docs.pinecone.io/reference/api/database-limits/identifier-limits Maximum length and allowed characters for Pinecone identifiers, including organization, project, index, namespace, and record names. An identifier is a string of characters used to identify "named" [objects in Pinecone](/guides/get-started/key-terms). The following Pinecone objects use strings as identifiers: | Object | Field | Max # characters | Allowed characters | | - | - | - | - | | [Organization](/guides/get-started/key-terms#organization) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Project](/guides/get-started/key-terms#project) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Index](/guides/get-started/key-terms#index) | `name` | 45 |
  • `a-z`, `0-9`, and `-`
  • Must be lowercase
  • Cannot start or end with `-`
  • Cannot be empty
| | [Namespace](/guides/get-started/key-terms#namespace) | `namespace` | 512 |
  • ASCII except `\0`
  • For the default namespace, use `""` (or `"__default__"`, in API versions `2025-04` and later)
| | [Namespace alias](/guides/data/namespace-aliases/overview) | `name` | 512 |
  • ASCII graphic characters
  • No spaces or `/ ? # % & = \ ; +`
  • `.`, `..`, and `__default__` are reserved
  • Must be unique in the index and can't match a namespace name
| | [Record](/guides/get-started/key-terms#record) | `id` | 512 |
  • ASCII except `\0`
  • Cannot be empty
| # Object limits Source: https://docs.pinecone.io/reference/api/database-limits/object-limits Limits on the number and size of Pinecone Database projects, indexes, namespaces, storage, backups, and collections, by plan. Object limits are restrictions on the number or size of objects in Pinecone. They vary based on [pricing plan](https://www.pinecone.io/pricing/). | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | Projects per organization | 1 | 5 | 20 | 100 | | Users per organization | 2 | 5 | Unlimited | Unlimited | | Serverless indexes per project 1 | 5 | 10 | 20 | 200 | | Serverless index storage per org | 2 GB | 10 GB | N/A | N/A | | Namespaces per serverless index | 100 | 1,000 | 100,000 | 1,000,000 | | Namespace aliases per serverless index | 1,000 | 1,000 | 1,000 | 1,000 | | Serverless backups per project | N/A | N/A | 500 | 1,000 | | 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/indexes/index-configuration#cloud-regions).\ When you exceed an object limit, API operations return a `403 - QUOTA_EXCEEDED`. [Upgrade your plan](/admin/billing/upgrade-billing-plan) to increase the limit. If a higher plan still doesn't cover what you need, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case, since most object limits can be raised on request. > [accordion] Example error > > ``` > Request failed. You've reached the max projects allowed in organization . > To add more projects, upgrade your plan. > ``` For the serverless storage limit, you can also [delete records](/guides/data/delete-data) to get back under it. > [!TIP] > > To stay under the serverless index limit, use [namespaces](/guides/indexes/create-an-index#namespaces) to partition data within a single index instead of creating multiple indexes. This can also improve query performance and lower costs by limiting searches to relevant data subsets. > [!NOTE] > > [Namespaces per serverless index](/reference/api/database-limits/object-limits) vary by plan (100 on Starter to 1,000,000 on Enterprise). Pinecone can accommodate more for specific use cases. If your application needs a higher limit, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). # Operation limits Source: https://docs.pinecone.io/reference/api/database-limits/operation-limits Fixed limits on Pinecone Database operations, including upsert, update, import, query, fetch, and delete batch sizes and metadata filter expressions. Operation limits are restrictions on the size, number, or other characteristics of operations in Pinecone. Operation limits are fixed and don't vary based on pricing plan. If one of these limits is blocking you, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. There's often a workaround. ## Upsert limits | Metric | Limit | | :- | :- | | Max [batch size](/guides/legacy/vectors-api/upsert-vectors#upsert-in-batches) for records with vectors | 1,000 records, up to 2 MB total | | Max batch size for records with text | 96 records | | Max documents per upsert request | 1,000, or 96 when the schema declares `embed` or `sparse_embed` | | 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](/guides/search/full-text-search/text-processing#tokens-and-analyzers) | 1,024 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 limit for text is lower because Pinecone converts that text to vectors at upsert time with [integrated embedding](/guides/indexes/index-data-overview#integrated-embedding), and 96 is the max batch size of the [hosted embedding models](/guides/indexes/index-configuration#embedding-models) doing the conversion. The 40 KB filterable metadata limit doesn't apply to `full_text_search` text fields. ## Update limits | Metric | Limit | | :- | :- | | Max documents per by-ID document update request | 1,000, or 96 when the schema declares `embed` or `sparse_embed` | | Max records per update-by-metadata request | 100,000 | ## Import limits > [!NOTE] > > If your import exceeds these limits, you'll get an error specifying the limit exceeded. See [Troubleshooting](/guides/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 doesn't apply to indexes with [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview). Bulk import supports indexes without a schema definition (Parquet files) and indexes with document schemas ([JSONL files](/guides/data/import-data#prepare-document-schema-files-jsonl)). Semantic-text (auto-embedded) fields aren't 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. > [!TIP] > > 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/legacy/vectors-api/fetch-vectors#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 returns 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 multitenancy](/guides/data/design-for-multitenancy). * **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 multitenancy](/guides/data/design-for-multitenancy#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. > [!TIP] > > 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. # Rate limits Source: https://docs.pinecone.io/reference/api/database-limits/rate-limits Request-per-second, monthly usage, and model throughput limits for Pinecone Database serverless indexes, and the 429 errors returned when you exceed them. Rate limits help protect your applications from misuse and maintain the health of our shared serverless infrastructure. They vary by [pricing plan](https://www.pinecone.io/pricing/) and apply to [serverless indexes](/guides/indexes/index-data-overview) only. Request-per-second limits are enforced per namespace or per index, as noted in the [Data operation throughput limits](#data-operation-throughput-limits) table, in addition to your read and write unit limits, so a request fails if it exceeds any applicable limit. When you exceed a limit, the request returns a `429 - TOO_MANY_REQUESTS` and the error message names the limit, scope, and value. **Most rate limits can be adjusted upon request.** If you need higher limits, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. > [!NOTE] > > Indexes built on [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) aren't subject to read unit limits for query, fetch, list, and full-text search operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) guide. ## Monthly usage limits [Read units](/guides/cost/understand-cost#read-units) and [write units](/guides/cost/understand-cost#write-units) measure resource consumption. To check your current usage, see [Download a usage report](/admin/billing/download-usage-report). | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | Read units per month per org | 1,000,000 | 2,000,000 | Unlimited | Unlimited | | Write units per month per org | 2,000,000 | 5,000,000 | Unlimited | Unlimited | | Embedding tokens per month per model | 5,000,000 | 10,000,000 | Unlimited | Unlimited | | `gemini-embedding-2` embedding tokens per month | Not available | 10,000,000 | Unlimited | Unlimited | > [!NOTE] > > From November 4 through December 31, 2026, Starter orgs get 10,000,000 embedding tokens per month per model, and Builder orgs get 20,000,000. Allowances return to the values in the table on January 1, 2027. Monthly rerank request limits vary by model: | Reranking model | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | `cohere-rerank-4-fast` | Not available | Not available | Unlimited | Unlimited | | `bge-reranker-v2-m3` | 500 | 1,000 | Unlimited | Unlimited | | `pinecone-rerank-v0` | 500 | Not available | Unlimited | Unlimited | Reaching a monthly usage limit returns a `429 - TOO_MANY_REQUESTS`. [Upgrade your plan](/admin/billing/upgrade-billing-plan) to continue. > [accordion] Example error > > ``` > Request failed. You've reached your read unit limit for the current month. > To continue reading data, upgrade your plan. > ``` ## Data operation throughput limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | Upsert size per second per namespace | 50 MB | 50 MB | 50 MB | 50 MB | | Query read units per second per namespace | 2,000 | 2,000 | 2,000 | 2,000 | | Query read units per second per index | 2,000 | 2,000 | 2,000 | 2,000 | | Query requests per second per namespace | 100 | 100 | 100 | 100 | | Update records per second per namespace | 100 | 100 | 100 | 100 | | Update requests per second per namespace | 100 | 100 | 100 | 100 | | Update by metadata requests per second per namespace | 20 | 20 | 20 | 20 | | Update by metadata requests per second per index | 500 | 500 | 500 | 500 | | Upsert requests per second per namespace | 100 | 100 | 100 | 100 | | Fetch requests per second per index | 100 | 100 | 100 | 100 | | List requests per second per index | 200 | 200 | 200 | 200 | | Describe index stats requests per second per index | 100 | 100 | 100 | 100 | | Delete requests per second per namespace | 100 | 100 | 100 | 100 | | Delete records per second per namespace | 5,000 | 5,000 | 5,000 | 5,000 | | Delete records per second per index | 5,000 | 5,000 | 5,000 | 5,000 | | Delete by metadata requests per second per namespace | 20 | 20 | 20 | 20 | | Delete by metadata requests per second per index | 500 | 500 | 500 | 500 | The per-namespace and per-index query read unit limits are enforced separately. At the defaults they're equal, so the namespace limit only matters once the index limit is raised. When you ask Support for a higher read limit, ask for both, or each namespace stays capped at its current limit. Exceeding a per-second throughput limit returns a `429 - TOO_MANY_REQUESTS`. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic), pace your requests, consider [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) (which aren't subject to per-second read limits) for high-throughput reads, or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) to raise a limit. > [accordion] Example 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. > ``` ## Model throughput limits Per-minute token limits for embedding models: | 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 | | `gemini-embedding-2` | Passage | Not available | 250,000 | 2,000,000 | 2,000,000 | | | Query | Not available | 50,000 | 250,000 | 250,000 | | `text-embedding-3-small` | Passage | 250,000 | 250,000 | 2,000,000 | 2,000,000 | | | Query | 50,000 | 50,000 | 250,000 | 250,000 | | `text-embedding-3-large` | Passage | 250,000 | 250,000 | 2,000,000 | 2,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 | Per-minute request limits for reranking models: | Reranking model | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | `cohere-rerank-4-fast` | Not available | Not available | 300 | 300 | | `bge-reranker-v2-m3` | 60 | 60 | 60 | 60 | | `pinecone-rerank-v0` | 60 | Not available | 60 | 60 | Reaching a per-minute model limit returns a `429 - TOO_MANY_REQUESTS`. [Upgrade your plan](/admin/billing/upgrade-billing-plan) to increase it, or [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). > [accordion] Example 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. > ``` ## Inference request limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | Inference requests per second per project | 100 | 100 | 100 | 100 | | Inference requests per minute per project | 2,000 | 2,000 | 2,000 | 2,000 | These limits apply per project across all models. Every inference request counts toward them, including requests that a [per-minute token limit](#model-throughput-limits) then rejects. Exceeding the per-second or per-minute limit returns a `429 - TOO_MANY_REQUESTS`. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle it. > [accordion] Example error > > ``` > Request failed. You've reached the max inference requests per second () for the current project. > ``` > > The message names the per-second or per-minute limit, whichever you exceeded. # Pinecone API errors Source: https://docs.pinecone.io/reference/api/errors Look up the HTTP status codes the Pinecone API returns, plus the causes and fixes for common Pinecone API and SDK error messages. Look up an [HTTP status code](#http-status-codes), or find an exact error message under [Index creation errors](#index-creation-errors) or [Outdated Python SDK errors](#outdated-python-sdk-errors). For handling errors in production, see [Error handling](/guides/production/error-handling). ## HTTP status codes 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. ### 200 - OK The request succeeded. ### 201 - CREATED The request succeeded and a new resource was created. ### 202 - ACCEPTED The request was accepted, but the operation isn't complete yet. For example, deleting an index returns `202` while the deletion is still in progress. ### 204 - NO CONTENT The request succeeded, and there's no response body 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](/admin/projects/projects-overview#api-keys). ### 402 - PAYMENT REQUIRED The request failed due to delinquent payment or account deactivation for non-payment. See [Account deactivation for non-payment](/admin/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/indexes/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. ## Index creation errors ### Missing spec argument ```console theme={null} TypeError: Pinecone.create_index() missing 1 required positional argument: 'spec' ``` Python SDK versions 3.0.0 to 9.x require a `spec` argument in `create_index()`. Pass one to set the index's cloud and region: ```python Python theme={null} from pinecone import Pinecone, 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"), ) ``` In Python SDK 10, `spec` is optional and new indexes default to AWS `us-east-1`. For current syntax, see [Create an index](/guides/indexes/create-an-index). ### Serverless index limit reached ```console theme={null} Request failed. You've reached the max serverless indexes allowed in project PROJECT_NAME (LIMIT). Use namespaces to partition your data into logical groups, or upgrade your plan to add more serverless indexes. ``` The API returns this with status `403` when the project already has as many serverless indexes as your plan allows. For the limit on each plan, see [Object limits](/reference/api/database-limits/object-limits). To fix it, do one of the following: * [Delete indexes](/guides/indexes/manage-indexes#delete-an-index) you no longer need. * Store data in [namespaces](/guides/data/implement-multitenancy) within one index instead of creating separate indexes. * [Upgrade your plan](/admin/billing/upgrade-billing-plan). ## Outdated Python SDK errors These errors come from code written for Python SDK versions earlier than 3.0.0, or from having the deprecated `pinecone-client` package installed. ### Pinecone has no attribute init ```console theme={null} AttributeError: module 'pinecone' has no attribute 'init' ``` In Python SDK 5.0.0 and later, the message reads: ```console theme={null} AttributeError: init is no longer a top-level attribute of the pinecone package. Please create an instance of the Pinecone class instead. ``` The code calls `pinecone.init()`, which was removed in version 3.0.0. Create a client instance instead. It doesn't take an environment, only an API key: ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` The same applies to other former top-level functions, such as `pinecone.create_index()` and `pinecone.list_indexes()`. Call them on the client instance instead. ### Cannot import name Pinecone ```console theme={null} ImportError: cannot import name 'Pinecone' from 'pinecone' ``` The installed SDK is earlier than 3.0.0, or the deprecated `pinecone-client` package is installed alongside `pinecone`. The Python SDK package was renamed from `pinecone-client` to `pinecone`, and having both installed causes conflicts. Remove the old package and upgrade: ```shell Shell theme={null} pip uninstall pinecone-client pip install --upgrade pinecone ``` ### Controller hostname not found ```console theme={null} Failed to resolve 'controller.us-west-2.pinecone.io' controller.us-west-2-aws.pinecone.io not found Request failed to reach Pinecone while calling https://controller.us-west-2.pinecone.io/actions/whoami ``` SDK versions earlier than 3.0.0 send requests to environment-specific `controller` hostnames. Current SDKs use `https://api.pinecone.io`. Upgrade the SDK, then update your code as described in [Pinecone has no attribute init](#pinecone-has-no-attribute-init): ```shell Shell theme={null} pip install --upgrade pinecone ``` # 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. > [!NOTE] > > [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: > [card] [CLI](/reference/cli/overview) > [card] [Python SDK](/reference/sdks/python/overview) > [card] [Node.js SDK](/reference/sdks/node/overview) > [card] [Java SDK](/reference/sdks/java/overview) > [card] [Go SDK](/reference/sdks/go/overview) ## Inference Use the Inference API to generate vector embeddings and rerank results using [embedding models](/guides/indexes/index-configuration#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-results) and [Generate vectors](/reference/api/latest/inference/generate-vectors) 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: > [card] [Python SDK](/reference/sdks/python/overview) > [card] [Node.js SDK](/reference/sdks/node/overview) > [card] [Java SDK](/reference/sdks/java/overview) > [card] [Go SDK](/reference/sdks/go/overview) # 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. ## Upserts * Pinecone is eventually consistent, so there can be a slight delay before [upserted records](/guides/data/upsert-data) are available to query. After upserting records, use the [Get index stats](/reference/api/latest/data-plane/describeindexstats) operation to check whether 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/indexes/index-data-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 don't support sparse vectors. ## Metadata * Null metadata values aren't supported. Instead of setting a key to `null`, remove the key from the metadata payload. * Nested JSON objects aren't supported. ## Serverless indexes Serverless indexes don't support the following features: * [Filtering index statistics by metadata](/reference/api/latest/data-plane/describeindexstats) * [Private endpoints](/guides/production/configure-private-endpoints) * This feature is available on AWS only. # Pinecone API versioning Source: https://docs.pinecone.io/reference/api/versioning Learn how Pinecone versions its APIs by release date, how long each stable version is supported, and how to set the X-Pinecone-Api-Version header. 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: ![](https://mintcdn.com/pinecone/9qvQp5nU6duJvusQ/images/api-versioning.png?fit=max\&auto=format\&n=9qvQp5nU6duJvusQ\&q=85\&s=be4366853edee83e003c3863e31fa1ce) ## Specify an API version > [!WARNING] > > 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-07`) 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-07" ``` 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 [changelog](/release-notes). # Create a cost usage export Source: https://docs.pinecone.io/reference/api/2026-07/admin/cost-usage-exports/create-a-cost-usage-export https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml post /admin/cost-usage-exports Start an asynchronous export of an organization's cost usage data. Only one export can run at a time and only a limited number of exports can be triggered per hour. The generated file is kept for two days. # Get cost usage export details Source: https://docs.pinecone.io/reference/api/2026-07/admin/cost-usage-exports/get-cost-usage-export-details https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml get /admin/cost-usage-exports/{cost_usage_export_id} Get the state of a cost usage export, and a link to download its file once the export has completed. A fresh signed link, valid for one hour, is generated on each read. # List cost usage exports Source: https://docs.pinecone.io/reference/api/2026-07/admin/cost-usage-exports/list-cost-usage-exports https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml get /admin/cost-usage-exports List the cost usage exports belonging to your organization, newest first. List items never carry a download link: `download_url` and `download_url_expires_at` are always `null` here. Request a single export to generate one. # Create a role binding Source: https://docs.pinecone.io/reference/api/2026-07/admin/role-bindings/create-a-role-binding https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml post /admin/role-bindings Grant a role to a principal at an organization or project scope. # Delete a role binding Source: https://docs.pinecone.io/reference/api/2026-07/admin/role-bindings/delete-a-role-binding https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml delete /admin/role-bindings/{role_binding_id} Delete a role binding; permissions are revoked when the deletion completes. # Get role binding details Source: https://docs.pinecone.io/reference/api/2026-07/admin/role-bindings/get-role-binding-details https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml get /admin/role-bindings/{role_binding_id} Get a role binding in the caller's organization by ID. # List role bindings Source: https://docs.pinecone.io/reference/api/2026-07/admin/role-bindings/list-role-bindings https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml get /admin/role-bindings List role bindings in the caller's organization, optionally filtered by principal, resource, and role. # Delete a service account Source: https://docs.pinecone.io/reference/api/2026-07/admin/service-accounts/delete-a-service-account https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.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. # Rotate a service account's OAuth client secret Source: https://docs.pinecone.io/reference/api/2026-07/admin/service-accounts/rotate-a-service-accounts-oauth-client-secret https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.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. # Update a service account Source: https://docs.pinecone.io/reference/api/2026-07/admin/service-accounts/update-a-service-account https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/admin_2026-07.oas.yaml patch /admin/service-accounts/{service_account_id} Update a service account's name; role bindings are managed through the role-binding endpoints. # Pinecone API 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](/admin/security/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; 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", "disabled", null); } } ``` ```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: 2026-07" \ -d '{ "name": "docs-example", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "_values": { "type": "dense_vector", "dimension": 1536, "metric": "cosine" } } } }' ``` ## Add headers to an HTTP request All HTTP requests to Pinecone APIs must contain an `Api-Key` header that specifies a valid [API key](/admin/security/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: 2026-07" \ -d '{ "name": "docs-example", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "_values": { "type": "dense_vector", "dimension": 1536, "metric": "cosine" } } } }' ``` ## Troubleshooting > [accordion] Initialization errors due to outdated SDKs > > 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 overview Source: https://docs.pinecone.io/reference/api/database-limits Reference for Pinecone Database rate, object, operation, and identifier limits, plus known index and serverless limitations. This page describes the limits and known limitations for Pinecone Database. Each topic has its own reference page: * **[Rate limits](/reference/api/database-limits/rate-limits)**: request-per-second, monthly usage, and model throughput limits that vary by pricing plan, plus the `429` errors you get when you exceed them. * **[Object limits](/reference/api/database-limits/object-limits)**: the number or size of projects, users, indexes, namespaces, storage, backups, and collections allowed by plan. * **[Operation limits](/reference/api/database-limits/operation-limits)**: fixed batch-size limits for upsert, import, query, fetch, and delete, plus metadata filter limits. * **[Identifier limits](/reference/api/database-limits/identifier-limits)**: maximum length and allowed characters for organization, project, index, namespace, and record identifiers. * **[Known limitations](/reference/api/known-limitations)**: index and serverless caveats, such as upsert consistency and metadata rules. > [!NOTE] > > If a limit is blocking you, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. Many limits can be raised on request, and Support can often suggest a workaround for the ones that can't. # Identifier limits Source: https://docs.pinecone.io/reference/api/database-limits/identifier-limits Maximum length and allowed characters for Pinecone identifiers, including organization, project, index, namespace, and record names. An identifier is a string of characters used to identify "named" [objects in Pinecone](/guides/get-started/key-terms). The following Pinecone objects use strings as identifiers: | Object | Field | Max # characters | Allowed characters | | - | - | - | - | | [Organization](/guides/get-started/key-terms#organization) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Project](/guides/get-started/key-terms#project) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Index](/guides/get-started/key-terms#index) | `name` | 45 |
  • `a-z`, `0-9`, and `-`
  • Must be lowercase
  • Cannot start or end with `-`
  • Cannot be empty
| | [Namespace](/guides/get-started/key-terms#namespace) | `namespace` | 512 |
  • ASCII except `\0`
  • For the default namespace, use `""` (or `"__default__"`, in API versions `2025-04` and later)
| | [Namespace alias](/guides/data/namespace-aliases/overview) | `name` | 512 |
  • ASCII graphic characters
  • No spaces or `/ ? # % & = \ ; +`
  • `.`, `..`, and `__default__` are reserved
  • Must be unique in the index and can't match a namespace name
| | [Record](/guides/get-started/key-terms#record) | `id` | 512 |
  • ASCII except `\0`
  • Cannot be empty
| # Object limits Source: https://docs.pinecone.io/reference/api/database-limits/object-limits Limits on the number and size of Pinecone Database projects, indexes, namespaces, storage, backups, and collections, by plan. Object limits are restrictions on the number or size of objects in Pinecone. They vary based on [pricing plan](https://www.pinecone.io/pricing/). | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | Projects per organization | 1 | 5 | 20 | 100 | | Users per organization | 2 | 5 | Unlimited | Unlimited | | Serverless indexes per project 1 | 5 | 10 | 20 | 200 | | Serverless index storage per org | 2 GB | 10 GB | N/A | N/A | | Namespaces per serverless index | 100 | 1,000 | 100,000 | 1,000,000 | | Namespace aliases per serverless index | 1,000 | 1,000 | 1,000 | 1,000 | | Serverless backups per project | N/A | N/A | 500 | 1,000 | | 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/indexes/index-configuration#cloud-regions).\ When you exceed an object limit, API operations return a `403 - QUOTA_EXCEEDED`. [Upgrade your plan](/admin/billing/upgrade-billing-plan) to increase the limit. If a higher plan still doesn't cover what you need, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case, since most object limits can be raised on request. > [accordion] Example error > > ``` > Request failed. You've reached the max projects allowed in organization . > To add more projects, upgrade your plan. > ``` For the serverless storage limit, you can also [delete records](/guides/data/delete-data) to get back under it. > [!TIP] > > To stay under the serverless index limit, use [namespaces](/guides/indexes/create-an-index#namespaces) to partition data within a single index instead of creating multiple indexes. This can also improve query performance and lower costs by limiting searches to relevant data subsets. > [!NOTE] > > [Namespaces per serverless index](/reference/api/database-limits/object-limits) vary by plan (100 on Starter to 1,000,000 on Enterprise). Pinecone can accommodate more for specific use cases. If your application needs a higher limit, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). # Operation limits Source: https://docs.pinecone.io/reference/api/database-limits/operation-limits Fixed limits on Pinecone Database operations, including upsert, update, import, query, fetch, and delete batch sizes and metadata filter expressions. Operation limits are restrictions on the size, number, or other characteristics of operations in Pinecone. Operation limits are fixed and don't vary based on pricing plan. If one of these limits is blocking you, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. There's often a workaround. ## Upsert limits | Metric | Limit | | :- | :- | | Max [batch size](/guides/legacy/vectors-api/upsert-vectors#upsert-in-batches) for records with vectors | 1,000 records, up to 2 MB total | | Max batch size for records with text | 96 records | | Max documents per upsert request | 1,000, or 96 when the schema declares `embed` or `sparse_embed` | | 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](/guides/search/full-text-search/text-processing#tokens-and-analyzers) | 1,024 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 limit for text is lower because Pinecone converts that text to vectors at upsert time with [integrated embedding](/guides/indexes/index-data-overview#integrated-embedding), and 96 is the max batch size of the [hosted embedding models](/guides/indexes/index-configuration#embedding-models) doing the conversion. The 40 KB filterable metadata limit doesn't apply to `full_text_search` text fields. ## Update limits | Metric | Limit | | :- | :- | | Max documents per by-ID document update request | 1,000, or 96 when the schema declares `embed` or `sparse_embed` | | Max records per update-by-metadata request | 100,000 | ## Import limits > [!NOTE] > > If your import exceeds these limits, you'll get an error specifying the limit exceeded. See [Troubleshooting](/guides/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 doesn't apply to indexes with [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview). Bulk import supports indexes without a schema definition (Parquet files) and indexes with document schemas ([JSONL files](/guides/data/import-data#prepare-document-schema-files-jsonl)). Semantic-text (auto-embedded) fields aren't 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. > [!TIP] > > 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/legacy/vectors-api/fetch-vectors#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 returns 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 multitenancy](/guides/data/design-for-multitenancy). * **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 multitenancy](/guides/data/design-for-multitenancy#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. > [!TIP] > > 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. # Rate limits Source: https://docs.pinecone.io/reference/api/database-limits/rate-limits Request-per-second, monthly usage, and model throughput limits for Pinecone Database serverless indexes, and the 429 errors returned when you exceed them. Rate limits help protect your applications from misuse and maintain the health of our shared serverless infrastructure. They vary by [pricing plan](https://www.pinecone.io/pricing/) and apply to [serverless indexes](/guides/indexes/index-data-overview) only. Request-per-second limits are enforced per namespace or per index, as noted in the [Data operation throughput limits](#data-operation-throughput-limits) table, in addition to your read and write unit limits, so a request fails if it exceeds any applicable limit. When you exceed a limit, the request returns a `429 - TOO_MANY_REQUESTS` and the error message names the limit, scope, and value. **Most rate limits can be adjusted upon request.** If you need higher limits, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. > [!NOTE] > > Indexes built on [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) aren't subject to read unit limits for query, fetch, list, and full-text search operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) guide. ## Monthly usage limits [Read units](/guides/cost/understand-cost#read-units) and [write units](/guides/cost/understand-cost#write-units) measure resource consumption. To check your current usage, see [Download a usage report](/admin/billing/download-usage-report). | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | Read units per month per org | 1,000,000 | 2,000,000 | Unlimited | Unlimited | | Write units per month per org | 2,000,000 | 5,000,000 | Unlimited | Unlimited | | Embedding tokens per month per model | 5,000,000 | 10,000,000 | Unlimited | Unlimited | | `gemini-embedding-2` embedding tokens per month | Not available | 10,000,000 | Unlimited | Unlimited | > [!NOTE] > > From November 4 through December 31, 2026, Starter orgs get 10,000,000 embedding tokens per month per model, and Builder orgs get 20,000,000. Allowances return to the values in the table on January 1, 2027. Monthly rerank request limits vary by model: | Reranking model | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | `cohere-rerank-4-fast` | Not available | Not available | Unlimited | Unlimited | | `bge-reranker-v2-m3` | 500 | 1,000 | Unlimited | Unlimited | | `pinecone-rerank-v0` | 500 | Not available | Unlimited | Unlimited | Reaching a monthly usage limit returns a `429 - TOO_MANY_REQUESTS`. [Upgrade your plan](/admin/billing/upgrade-billing-plan) to continue. > [accordion] Example error > > ``` > Request failed. You've reached your read unit limit for the current month. > To continue reading data, upgrade your plan. > ``` ## Data operation throughput limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | Upsert size per second per namespace | 50 MB | 50 MB | 50 MB | 50 MB | | Query read units per second per namespace | 2,000 | 2,000 | 2,000 | 2,000 | | Query read units per second per index | 2,000 | 2,000 | 2,000 | 2,000 | | Query requests per second per namespace | 100 | 100 | 100 | 100 | | Update records per second per namespace | 100 | 100 | 100 | 100 | | Update requests per second per namespace | 100 | 100 | 100 | 100 | | Update by metadata requests per second per namespace | 20 | 20 | 20 | 20 | | Update by metadata requests per second per index | 500 | 500 | 500 | 500 | | Upsert requests per second per namespace | 100 | 100 | 100 | 100 | | Fetch requests per second per index | 100 | 100 | 100 | 100 | | List requests per second per index | 200 | 200 | 200 | 200 | | Describe index stats requests per second per index | 100 | 100 | 100 | 100 | | Delete requests per second per namespace | 100 | 100 | 100 | 100 | | Delete records per second per namespace | 5,000 | 5,000 | 5,000 | 5,000 | | Delete records per second per index | 5,000 | 5,000 | 5,000 | 5,000 | | Delete by metadata requests per second per namespace | 20 | 20 | 20 | 20 | | Delete by metadata requests per second per index | 500 | 500 | 500 | 500 | The per-namespace and per-index query read unit limits are enforced separately. At the defaults they're equal, so the namespace limit only matters once the index limit is raised. When you ask Support for a higher read limit, ask for both, or each namespace stays capped at its current limit. Exceeding a per-second throughput limit returns a `429 - TOO_MANY_REQUESTS`. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic), pace your requests, consider [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) (which aren't subject to per-second read limits) for high-throughput reads, or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) to raise a limit. > [accordion] Example 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. > ``` ## Model throughput limits Per-minute token limits for embedding models: | 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 | | `gemini-embedding-2` | Passage | Not available | 250,000 | 2,000,000 | 2,000,000 | | | Query | Not available | 50,000 | 250,000 | 250,000 | | `text-embedding-3-small` | Passage | 250,000 | 250,000 | 2,000,000 | 2,000,000 | | | Query | 50,000 | 50,000 | 250,000 | 250,000 | | `text-embedding-3-large` | Passage | 250,000 | 250,000 | 2,000,000 | 2,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 | Per-minute request limits for reranking models: | Reranking model | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | `cohere-rerank-4-fast` | Not available | Not available | 300 | 300 | | `bge-reranker-v2-m3` | 60 | 60 | 60 | 60 | | `pinecone-rerank-v0` | 60 | Not available | 60 | 60 | Reaching a per-minute model limit returns a `429 - TOO_MANY_REQUESTS`. [Upgrade your plan](/admin/billing/upgrade-billing-plan) to increase it, or [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). > [accordion] Example 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. > ``` ## Inference request limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | Inference requests per second per project | 100 | 100 | 100 | 100 | | Inference requests per minute per project | 2,000 | 2,000 | 2,000 | 2,000 | These limits apply per project across all models. Every inference request counts toward them, including requests that a [per-minute token limit](#model-throughput-limits) then rejects. Exceeding the per-second or per-minute limit returns a `429 - TOO_MANY_REQUESTS`. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle it. > [accordion] Example error > > ``` > Request failed. You've reached the max inference requests per second () for the current project. > ``` > > The message names the per-second or per-minute limit, whichever you exceeded. # Pinecone API errors Source: https://docs.pinecone.io/reference/api/errors Look up the HTTP status codes the Pinecone API returns, plus the causes and fixes for common Pinecone API and SDK error messages. Look up an [HTTP status code](#http-status-codes), or find an exact error message under [Index creation errors](#index-creation-errors) or [Outdated Python SDK errors](#outdated-python-sdk-errors). For handling errors in production, see [Error handling](/guides/production/error-handling). ## HTTP status codes 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. ### 200 - OK The request succeeded. ### 201 - CREATED The request succeeded and a new resource was created. ### 202 - ACCEPTED The request was accepted, but the operation isn't complete yet. For example, deleting an index returns `202` while the deletion is still in progress. ### 204 - NO CONTENT The request succeeded, and there's no response body 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](/admin/projects/projects-overview#api-keys). ### 402 - PAYMENT REQUIRED The request failed due to delinquent payment or account deactivation for non-payment. See [Account deactivation for non-payment](/admin/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/indexes/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. ## Index creation errors ### Missing spec argument ```console theme={null} TypeError: Pinecone.create_index() missing 1 required positional argument: 'spec' ``` Python SDK versions 3.0.0 to 9.x require a `spec` argument in `create_index()`. Pass one to set the index's cloud and region: ```python Python theme={null} from pinecone import Pinecone, 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"), ) ``` In Python SDK 10, `spec` is optional and new indexes default to AWS `us-east-1`. For current syntax, see [Create an index](/guides/indexes/create-an-index). ### Serverless index limit reached ```console theme={null} Request failed. You've reached the max serverless indexes allowed in project PROJECT_NAME (LIMIT). Use namespaces to partition your data into logical groups, or upgrade your plan to add more serverless indexes. ``` The API returns this with status `403` when the project already has as many serverless indexes as your plan allows. For the limit on each plan, see [Object limits](/reference/api/database-limits/object-limits). To fix it, do one of the following: * [Delete indexes](/guides/indexes/manage-indexes#delete-an-index) you no longer need. * Store data in [namespaces](/guides/data/implement-multitenancy) within one index instead of creating separate indexes. * [Upgrade your plan](/admin/billing/upgrade-billing-plan). ## Outdated Python SDK errors These errors come from code written for Python SDK versions earlier than 3.0.0, or from having the deprecated `pinecone-client` package installed. ### Pinecone has no attribute init ```console theme={null} AttributeError: module 'pinecone' has no attribute 'init' ``` In Python SDK 5.0.0 and later, the message reads: ```console theme={null} AttributeError: init is no longer a top-level attribute of the pinecone package. Please create an instance of the Pinecone class instead. ``` The code calls `pinecone.init()`, which was removed in version 3.0.0. Create a client instance instead. It doesn't take an environment, only an API key: ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` The same applies to other former top-level functions, such as `pinecone.create_index()` and `pinecone.list_indexes()`. Call them on the client instance instead. ### Cannot import name Pinecone ```console theme={null} ImportError: cannot import name 'Pinecone' from 'pinecone' ``` The installed SDK is earlier than 3.0.0, or the deprecated `pinecone-client` package is installed alongside `pinecone`. The Python SDK package was renamed from `pinecone-client` to `pinecone`, and having both installed causes conflicts. Remove the old package and upgrade: ```shell Shell theme={null} pip uninstall pinecone-client pip install --upgrade pinecone ``` ### Controller hostname not found ```console theme={null} Failed to resolve 'controller.us-west-2.pinecone.io' controller.us-west-2-aws.pinecone.io not found Request failed to reach Pinecone while calling https://controller.us-west-2.pinecone.io/actions/whoami ``` SDK versions earlier than 3.0.0 send requests to environment-specific `controller` hostnames. Current SDKs use `https://api.pinecone.io`. Upgrade the SDK, then update your code as described in [Pinecone has no attribute init](#pinecone-has-no-attribute-init): ```shell Shell theme={null} pip install --upgrade pinecone ``` # 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. > [!NOTE] > > [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: > [card] [CLI](/reference/cli/overview) > [card] [Python SDK](/reference/sdks/python/overview) > [card] [Node.js SDK](/reference/sdks/node/overview) > [card] [Java SDK](/reference/sdks/java/overview) > [card] [Go SDK](/reference/sdks/go/overview) ## Inference Use the Inference API to generate vector embeddings and rerank results using [embedding models](/guides/indexes/index-configuration#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-results) and [Generate vectors](/reference/api/latest/inference/generate-vectors) 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: > [card] [Python SDK](/reference/sdks/python/overview) > [card] [Node.js SDK](/reference/sdks/node/overview) > [card] [Java SDK](/reference/sdks/java/overview) > [card] [Go SDK](/reference/sdks/go/overview) # 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. ## Upserts * Pinecone is eventually consistent, so there can be a slight delay before [upserted records](/guides/data/upsert-data) are available to query. After upserting records, use the [Get index stats](/reference/api/latest/data-plane/describeindexstats) operation to check whether 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/indexes/index-data-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 don't support sparse vectors. ## Metadata * Null metadata values aren't supported. Instead of setting a key to `null`, remove the key from the metadata payload. * Nested JSON objects aren't supported. ## Serverless indexes Serverless indexes don't support the following features: * [Filtering index statistics by metadata](/reference/api/latest/data-plane/describeindexstats) * [Private endpoints](/guides/production/configure-private-endpoints) * This feature is available on AWS only. # Pinecone API versioning Source: https://docs.pinecone.io/reference/api/versioning Learn how Pinecone versions its APIs by release date, how long each stable version is supported, and how to set the X-Pinecone-Api-Version header. 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: ![](https://mintcdn.com/pinecone/9qvQp5nU6duJvusQ/images/api-versioning.png?fit=max\&auto=format\&n=9qvQp5nU6duJvusQ\&q=85\&s=be4366853edee83e003c3863e31fa1ce) ## Specify an API version > [!WARNING] > > 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-07`) 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-07" ``` 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 [changelog](/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](/admin/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](/admin/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" ``` > [!WARNING] > > 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 > [!NOTE] > > 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" ``` > [!NOTE] > > 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). > [!NOTE] > > `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 > [accordion] pc login (Authenticate via user login) > > **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" > ``` > > > [!NOTE] > > > > This is an alias for `pc auth login`. Both commands perform the same operation. > [accordion] pc logout (Clear credentials / log out) > > **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 > ``` > > > [!NOTE] > > > > 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. > [accordion] pc target (Set target organization and project) > > **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 > ``` > [accordion] pc version (Show CLI version) > > **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 > ``` > [accordion] pc whoami (Show current user) > > **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 > ``` > > > [!NOTE] > > > > This is an alias for `pc auth whoami`. Both commands perform the same operation. ### Authentication > [accordion] pc auth clear (Clear specific credentials) > > **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 > ``` > > > [!NOTE] > > > > 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`. > [accordion] pc auth configure (Configure service account or API key) > > **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 > ``` > > > [!NOTE] > > > > `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). > [accordion] pc auth local-keys list (List managed keys) > > **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 > ``` > [accordion] pc auth local-keys prune (Delete managed keys) > > **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 > ``` > > > [!NOTE] > > > > This deletes keys from both local storage and Pinecone servers. Use `--dry-run` to preview before committing. > [accordion] pc auth login (Authenticate via user login) > > **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 > ``` > > > [!NOTE] > > > > 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`. > [accordion] pc auth logout (Clear authentication credentials) > > **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 > ``` > > > [!NOTE] > > > > 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. > [accordion] pc auth status (Show authentication status) > > **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 > ``` > [accordion] pc auth whoami (Show current user information) > > **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 > ``` > > > [!NOTE] > > > > This command does the same thing as `pc whoami`. ### Indexes > [accordion] pc index configure (Update index configuration) > > **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 > ``` > > > [!NOTE] > > > > Configuration changes may take some time to take effect. > [accordion] pc index create (Create a new index) > > **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 > ``` > > > [!NOTE] > > > > For a list of valid regions for a serverless index, see [Create a serverless index](/guides/indexes/create-an-index). > [accordion] pc index delete (Delete 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 > ``` > > > [!NOTE] > > > > This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. > [accordion] pc index describe (Show index details) > > **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 > ``` > [accordion] pc index stats (Show index statistics) > > **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 > ``` > [accordion] pc index list (List all indexes) > > **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 > [accordion] pc index namespace create (Create a namespace) > > **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 > ``` > [accordion] pc index namespace delete (Delete a namespace) > > **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 > ``` > > > [!WARNING] > > > > Deleting a namespace removes all vectors in that namespace. This operation cannot be undone. > [accordion] pc index namespace describe (Show namespace details) > > **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 > ``` > [accordion] pc index namespace list (List namespaces) > > **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 > [accordion] pc index vector delete (Delete 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 > ``` > > > [!NOTE] > > > > 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. > > > [!WARNING] > > > > Vector deletion is permanent and cannot be undone. > [accordion] pc index vector fetch (Fetch vectors by ID or filter) > > **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 > ``` > > > [!NOTE] > > > > Use either `--ids` or `--filter`, not both. When using `--ids`, pagination flags are not applicable. > [accordion] pc index vector list (List vector IDs) > > **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 > ``` > [accordion] pc index vector query (Query vectors) > > **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 > ``` > > > [!NOTE] > > > > Use `--id`, `--vector`, or sparse vectors (`--sparse-indices` and `--sparse-values`) to specify what to query against. These options are mutually exclusive. > [accordion] pc index vector update (Update vectors) > > **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"}' > ``` > > > [!NOTE] > > > > Use either `--id` for single vector updates or `--filter` for bulk updates. These options are mutually exclusive. > [accordion] pc index vector upsert (Upsert vectors) > > **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 > ``` > > > [!NOTE] > > > > **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 > [accordion] pc index record search (Search records in an index) > > **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..."} > ``` > [accordion] pc index record upsert (Upsert records into an integrated index) > > **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 > [accordion] pc index collection create (Create a collection from a pod-based index) > > **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 > ``` > [accordion] pc index collection delete (Delete a collection) > > **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 > ``` > > > [!NOTE] > > > > This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. > [accordion] pc index collection describe (Describe a collection by name) > > **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 > ``` > [accordion] pc index collection list (List collections in your project) > > **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 > [accordion] pc index backup create (Create a backup) > > **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 > ``` > [accordion] pc index backup delete (Delete a backup) > > **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 > ``` > > > [!NOTE] > > > > This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. > > > [!WARNING] > > > > Backup deletion is permanent and cannot be undone. > [accordion] pc index backup describe (Show backup details) > > **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 > ``` > [accordion] pc index backup list (List backups) > > **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 > ``` > [accordion] pc index restore (Restore an index from a backup) > > **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 > ``` > [accordion] pc index restore describe (Show restore job details) > > **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 > ``` > [accordion] pc index restore list (List restore jobs) > > **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 > [accordion] pc index import start (Start an import from a storage URI) > > **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 > ``` > [accordion] pc index import describe (Describe an import operation) > > **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 > ``` > [accordion] pc index import list (List import operations for an index) > > **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 - > ``` > [accordion] pc index import cancel (Cancel an in-progress import operation) > > **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 > [accordion] pc project create (Create a new project) > > **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" > ``` > [accordion] pc project delete (Delete a 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 > ``` > > > [!NOTE] > > > > 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. > [accordion] pc project describe (Show project details) > > **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 > ``` > [accordion] pc project list (List all projects) > > **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 > ``` > [accordion] pc project update (Update project settings) > > **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 > [accordion] pc organization delete (Delete an organization) > > **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 > ``` > > > [!NOTE] > > > > 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. > [accordion] pc organization describe (Show organization details) > > **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 > ``` > [accordion] pc organization list (List organizations) > > **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 > ``` > [accordion] pc organization update (Update organization settings) > > **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 > [accordion] pc api-key create (Create a new API key) > > **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 > ``` > > > [!NOTE] > > > > API keys are scoped to a specific organization and project. > [accordion] pc api-key delete (Delete an API key) > > **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 > ``` > > > [!NOTE] > > > > Deletion is permanent. Applications using this key immediately lose access to Pinecone. > [accordion] pc api-key describe (Show API key details) > > **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 > ``` > > > [!NOTE] > > > > Does not display the actual key value. > [accordion] pc api-key list (List all API keys) > > **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 > ``` > > > [!NOTE] > > > > Does not display key values. > [accordion] pc api-key update (Update API key settings) > > **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 > ``` > > > [!NOTE] > > > > Cannot change the actual key. If you need a different key, create a new one. ### Config > [accordion] pc config list (List all configuration settings and their current values) > > **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 > ``` > [accordion] pc config get \ (Get the current value of a configuration setting) > > **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 > ``` > [accordion] pc config describe \ (Show detailed information about a configuration setting) > > **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 > ``` > [accordion] pc config set \ \ (Set a configuration value) > > **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 > ``` > [accordion] pc config unset \ (Reset a configuration value to its default) > > **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 > [tab] macOS (Homebrew) > > ```bash theme={null} > brew tap pinecone-io/tap > brew install pinecone-io/tap/pinecone > ``` > [tab] Other platforms > > 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" ``` > [!TIP] > > 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 Set the Pinecone CLI target context with pc target to control which organization and project your commands run against, including in CI/CD and JSON mode. 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. | > [!NOTE] > > `--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 > [!WARNING] > > 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 can't 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 don't 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). > [card] [Python SDK](/reference/sdks/python/overview) > [card] [Node.js SDK](/reference/sdks/node/overview) > [card] [Java SDK](/reference/sdks/java/overview) > [card] [Go SDK](/reference/sdks/go/overview) ## 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-07` | `2026-04` | `2025-10` | `2025-04` | `2025-01` | `2024-10` | `2024-07` | `2024-04` | | - | :- | :- | :- | :- | :- | :- | :- | :- | | [Python SDK](/reference/sdks/python/overview) | v10.x | 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) | v9.x | v8.x | v7.x | v6.x | v5.x | v4.x | v3.x | v2.x | | [Java SDK](/reference/sdks/java/overview) | Coming soon | Coming soon | v6.x | v5.x | v4.x | v3.x | v2.x | v1.x | | [Go SDK](/reference/sdks/go/overview) | v7.x | 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. > [!NOTE] > > 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 search, query, fetch, and list responses. For example, if a search 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/monitor-performance) or the organization-wide [Usage dashboard](/admin/billing/download-usage-report). ## Community SDKs Find community-contributed SDKs for Pinecone. These libraries aren't 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. > [!TIP] > > 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-07` | v7.x | | `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/v7/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/v7/pinecone@ ``` To check your SDK version, run the following command: ```shell theme={null} go list -u -m all | grep go-pinecone ``` ## Upgrade > [!WARNING] > > Before upgrading to `v7.0.0`, update all relevant code to account for the following breaking changes. See the [v7 migration guide](https://github.com/pinecone-io/go-pinecone/blob/main/guides/migration/v7.md) for before-and-after examples. > > * Pod-based index creation is removed. `CreatePodIndex` and `CreatePodIndexRequest` no longer exist, but existing pod-based indexes keep working. > * Enum constants are prefixed with their type name. For example, `Aws` is now `CloudAWS`, and `Cosine` is now `IndexMetricCosine`. > * `ListImports` takes a `*ListImportsRequest`, and `QueryByVectorIdRequest.SparseValues` is removed. > * `SourceCollection` and `Schema` on the legacy create requests now return an error. `ConfigureIndexParams.Embed` is replaced by `ConfigureIndexParams.Schema`. > * `Backup` field types changed, and some invalid requests now fail client-side. > > If you are upgrading from `v2` or earlier, also account for the `v3.0.0` 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 `v6` to `v7` means changing: ```go theme={null} // before import "github.com/pinecone-io/go-pinecone/v6/pinecone" // after import "github.com/pinecone-io/go-pinecone/v7/pinecone" ``` Apart from the module path, `v5.0.0` and `v6.0.0` are backward compatible with the release lines before them. `v7.0.0` targets API version `2026-07` and includes the breaking changes listed above. To stay on API version `2026-04`, keep using `v6`. 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/v7/pinecone@latest ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/admin/security/security-overview#api-keys) to initialize a client instance: ```Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v7/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](/admin/security/manage-rbac), initialize an `AdminClient` with [service account](/admin/organizations/manage-service-accounts) credentials instead: ```Go theme={null} package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v7/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) ``` > [!NOTE] > > 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)); ``` > [!TIP] > > 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) aren't currently instrumented. * **Bulk import operations** aren't yet instrumented. * **Server duration may be unavailable.** The `getServerDurationMs()` method returns `null` if the `x-pinecone-response-duration-ms` header isn't 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 don't 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 raised 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. > [!TIP] > > 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-10` | v6.x | | `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 6.3.0 # Gradle implementation "io.pinecone:pinecone-client:6.3.0" ``` Alternatively, you can download the standalone uberjar [pinecone-client-6.3.0-all.jar](https://repo1.maven.org/maven2/io/pinecone/pinecone-client/6.3.0/pinecone-client-6.3.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 > [!WARNING] > > Before upgrading from `v5.x` to `v6.x`, update code that passes enum values. Deletion protection, cloud, and import error mode now take strings, such as `"enabled"`, `"aws"`, and `"continue"`. For the full list of breaking changes, see the [`v6.0.0` release notes](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v6.0.0). 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 6.3.0 # Gradle implementation "io.pinecone:pinecone-client:6.3.0" ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/admin/security/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. > [!TIP] > > 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.js SDK requires Node.js 22 or later. Its type declarations support TypeScript 5.2 to 7.x. The SDK is for server-side use only. Running it in a browser exposes your API key, so call Pinecone from your backend instead. ## 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-07` | v9.x | | `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 `v9.0.0` targets API version `2026-07`. To stay on API version `2026-04`, keep using `v8`. The flat control methods, such as `pc.createIndex` and `pc.configureIndex`, still work in `v9` but are deprecated in favor of resource clients such as `pc.indexes`. > [!WARNING] > > Before upgrading to `v9.0.0`, update all relevant code to account for the following breaking changes. See the [v9 migration guide](https://github.com/pinecone-io/pinecone-ts-client/blob/main/guides/upgrading/v9-migration.md) for before-and-after examples. > > * Node.js 22 or later is required. > * `pc.preview` and the `Preview*` exports are removed. Document operations move to `index.documents`, where `index` comes from `pc.index({ name, namespace })` or `pc.index(name).namespace(namespace)`. Control operations move to resource clients such as `pc.indexes`. > * Pod-based index creation, legacy metadata-indexing schemas, and the `sourceCollection` and `sourceBackupId` creation options are rejected. Existing pod-based indexes keep working. To restore from a backup, use `pc.backups.createIndex(backupId, options)`. > * A top-level `embed` option when configuring an index is rejected. Update the semantic field through a `schema.fields` patch instead. > * Legacy index response properties such as `dimension`, `metric`, and `spec` are compatibility getters derived from `schema` and `deployment`. They are omitted when a response is spread or serialized, and can throw `Errors.PineconeIndexPropertyError` when there is no legacy equivalent. > * `NamespaceDescription.recordCount` and `sizeBytes` are now decimal strings, and `BackupModel.createdAt` is now a `Date`. > * Some generated type names are renamed or removed. For example, `BackupPaginationResponse` is now `BackupListPagination`. 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](/admin/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](/admin/security/manage-rbac), initialize an `AdminClient` with [service account](/admin/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. > [!NOTE] > > 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. > [!TIP] > > 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`. The base install includes the sync and [async](#async-requests) clients and the [gRPC](https://grpc.io/) data-plane client, so there are no extras to install. ## Requirements The Pinecone Python SDK requires Python 3.10 or later. It has been tested with CPython versions from 3.10 to 3.14. ## 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 | | :- | :- | | `2026-07` | v10.x | | `2026-04` | v9.x | | `2025-10` | v8.x | | `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 ``` To install a specific version of the Python SDK, run the following command: ```shell pip theme={null} # Install a specific version pip install pinecone== ``` SDK versions 8.x and earlier shipped gRPC and asyncio support as optional extras. To use them on those versions, install `"pinecone[grpc]=="` or `"pinecone[asyncio]=="`. To check your SDK version, run the following command: ```shell pip theme={null} pip show pinecone ``` > [!NOTE] > > 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's 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 > [!WARNING] > > 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 ``` ## Initialize Once installed, you can import the library and then use an [API key](/admin/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/indexes/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's disabled when set to `False`. It's 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 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 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/indexes/index-data-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. > [tab] Python SDK without gRPC > > When using the Python SDK without gRPC, to get good performance, it's 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 aren't 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) > ``` > [tab] Python SDK with gRPC > > When using the Python SDK with gRPC, 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 with the [Python SDK](/reference/sdks/python/overview), use the `upsert_from_dataframe` method. It upserts in batches (set the size with `batch_size`), retries failed requests, and performs especially well with data loaded from Parquet files. The dataframe needs `id` and `values` columns, plus an optional `metadata` column. ```Python Python theme={null} import pandas as pd from pinecone import Pinecone pc = Pinecone(api_key="API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/target-an-index index = pc.Index(host="INDEX_HOST") # To load a Parquet file instead, use pd.read_parquet("path/to/file.parquet") df = pd.DataFrame({ "id": ["A", "B", "C"], "values": [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6], [0.7, 0.8, 0.9]], "metadata": [{"genre": "drama"}, {"genre": "comedy"}, {"genre": "drama"}], }) index.upsert_from_dataframe(df, namespace="example-namespace", batch_size=500) ``` # 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 > [tab] Databricks platform > > 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.2.0/spark-pinecone-uberjar.jar > ``` > > > [!NOTE] > > > > Databricks platform users must use the Pinecone assembly jar listed above to ensure that the proper dependecies are installed. > > 3. Click **Install**. > [tab] Databricks on AWS > > 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.2.0/spark-pinecone-uberjar.jar > ``` > > 3. Click **Install**. > [tab] Databricks on GCP / Azure > > 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.2.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() } ``` > [!TIP] > > 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) # Pinecone API 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](/admin/security/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; 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", "disabled", null); } } ``` ```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: 2026-07" \ -d '{ "name": "docs-example", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "_values": { "type": "dense_vector", "dimension": 1536, "metric": "cosine" } } } }' ``` ## Add headers to an HTTP request All HTTP requests to Pinecone APIs must contain an `Api-Key` header that specifies a valid [API key](/admin/security/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: 2026-07" \ -d '{ "name": "docs-example", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "_values": { "type": "dense_vector", "dimension": 1536, "metric": "cosine" } } } }' ``` ## Troubleshooting > [accordion] Initialization errors due to outdated SDKs > > 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 overview Source: https://docs.pinecone.io/reference/api/database-limits Reference for Pinecone Database rate, object, operation, and identifier limits, plus known index and serverless limitations. This page describes the limits and known limitations for Pinecone Database. Each topic has its own reference page: * **[Rate limits](/reference/api/database-limits/rate-limits)**: request-per-second, monthly usage, and model throughput limits that vary by pricing plan, plus the `429` errors you get when you exceed them. * **[Object limits](/reference/api/database-limits/object-limits)**: the number or size of projects, users, indexes, namespaces, storage, backups, and collections allowed by plan. * **[Operation limits](/reference/api/database-limits/operation-limits)**: fixed batch-size limits for upsert, import, query, fetch, and delete, plus metadata filter limits. * **[Identifier limits](/reference/api/database-limits/identifier-limits)**: maximum length and allowed characters for organization, project, index, namespace, and record identifiers. * **[Known limitations](/reference/api/known-limitations)**: index and serverless caveats, such as upsert consistency and metadata rules. > [!NOTE] > > If a limit is blocking you, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. Many limits can be raised on request, and Support can often suggest a workaround for the ones that can't. # Identifier limits Source: https://docs.pinecone.io/reference/api/database-limits/identifier-limits Maximum length and allowed characters for Pinecone identifiers, including organization, project, index, namespace, and record names. An identifier is a string of characters used to identify "named" [objects in Pinecone](/guides/get-started/key-terms). The following Pinecone objects use strings as identifiers: | Object | Field | Max # characters | Allowed characters | | - | - | - | - | | [Organization](/guides/get-started/key-terms#organization) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Project](/guides/get-started/key-terms#project) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Index](/guides/get-started/key-terms#index) | `name` | 45 |
  • `a-z`, `0-9`, and `-`
  • Must be lowercase
  • Cannot start or end with `-`
  • Cannot be empty
| | [Namespace](/guides/get-started/key-terms#namespace) | `namespace` | 512 |
  • ASCII except `\0`
  • For the default namespace, use `""` (or `"__default__"`, in API versions `2025-04` and later)
| | [Namespace alias](/guides/data/namespace-aliases/overview) | `name` | 512 |
  • ASCII graphic characters
  • No spaces or `/ ? # % & = \ ; +`
  • `.`, `..`, and `__default__` are reserved
  • Must be unique in the index and can't match a namespace name
| | [Record](/guides/get-started/key-terms#record) | `id` | 512 |
  • ASCII except `\0`
  • Cannot be empty
| # Object limits Source: https://docs.pinecone.io/reference/api/database-limits/object-limits Limits on the number and size of Pinecone Database projects, indexes, namespaces, storage, backups, and collections, by plan. Object limits are restrictions on the number or size of objects in Pinecone. They vary based on [pricing plan](https://www.pinecone.io/pricing/). | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | Projects per organization | 1 | 5 | 20 | 100 | | Users per organization | 2 | 5 | Unlimited | Unlimited | | Serverless indexes per project 1 | 5 | 10 | 20 | 200 | | Serverless index storage per org | 2 GB | 10 GB | N/A | N/A | | Namespaces per serverless index | 100 | 1,000 | 100,000 | 1,000,000 | | Namespace aliases per serverless index | 1,000 | 1,000 | 1,000 | 1,000 | | Serverless backups per project | N/A | N/A | 500 | 1,000 | | 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/indexes/index-configuration#cloud-regions).\ When you exceed an object limit, API operations return a `403 - QUOTA_EXCEEDED`. [Upgrade your plan](/admin/billing/upgrade-billing-plan) to increase the limit. If a higher plan still doesn't cover what you need, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case, since most object limits can be raised on request. > [accordion] Example error > > ``` > Request failed. You've reached the max projects allowed in organization . > To add more projects, upgrade your plan. > ``` For the serverless storage limit, you can also [delete records](/guides/data/delete-data) to get back under it. > [!TIP] > > To stay under the serverless index limit, use [namespaces](/guides/indexes/create-an-index#namespaces) to partition data within a single index instead of creating multiple indexes. This can also improve query performance and lower costs by limiting searches to relevant data subsets. > [!NOTE] > > [Namespaces per serverless index](/reference/api/database-limits/object-limits) vary by plan (100 on Starter to 1,000,000 on Enterprise). Pinecone can accommodate more for specific use cases. If your application needs a higher limit, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). # Operation limits Source: https://docs.pinecone.io/reference/api/database-limits/operation-limits Fixed limits on Pinecone Database operations, including upsert, update, import, query, fetch, and delete batch sizes and metadata filter expressions. Operation limits are restrictions on the size, number, or other characteristics of operations in Pinecone. Operation limits are fixed and don't vary based on pricing plan. If one of these limits is blocking you, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. There's often a workaround. ## Upsert limits | Metric | Limit | | :- | :- | | Max [batch size](/guides/legacy/vectors-api/upsert-vectors#upsert-in-batches) for records with vectors | 1,000 records, up to 2 MB total | | Max batch size for records with text | 96 records | | Max documents per upsert request | 1,000, or 96 when the schema declares `embed` or `sparse_embed` | | 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](/guides/search/full-text-search/text-processing#tokens-and-analyzers) | 1,024 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 limit for text is lower because Pinecone converts that text to vectors at upsert time with [integrated embedding](/guides/indexes/index-data-overview#integrated-embedding), and 96 is the max batch size of the [hosted embedding models](/guides/indexes/index-configuration#embedding-models) doing the conversion. The 40 KB filterable metadata limit doesn't apply to `full_text_search` text fields. ## Update limits | Metric | Limit | | :- | :- | | Max documents per by-ID document update request | 1,000, or 96 when the schema declares `embed` or `sparse_embed` | | Max records per update-by-metadata request | 100,000 | ## Import limits > [!NOTE] > > If your import exceeds these limits, you'll get an error specifying the limit exceeded. See [Troubleshooting](/guides/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 doesn't apply to indexes with [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview). Bulk import supports indexes without a schema definition (Parquet files) and indexes with document schemas ([JSONL files](/guides/data/import-data#prepare-document-schema-files-jsonl)). Semantic-text (auto-embedded) fields aren't 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. > [!TIP] > > 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/legacy/vectors-api/fetch-vectors#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 returns 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 multitenancy](/guides/data/design-for-multitenancy). * **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 multitenancy](/guides/data/design-for-multitenancy#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. > [!TIP] > > 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. # Rate limits Source: https://docs.pinecone.io/reference/api/database-limits/rate-limits Request-per-second, monthly usage, and model throughput limits for Pinecone Database serverless indexes, and the 429 errors returned when you exceed them. Rate limits help protect your applications from misuse and maintain the health of our shared serverless infrastructure. They vary by [pricing plan](https://www.pinecone.io/pricing/) and apply to [serverless indexes](/guides/indexes/index-data-overview) only. Request-per-second limits are enforced per namespace or per index, as noted in the [Data operation throughput limits](#data-operation-throughput-limits) table, in addition to your read and write unit limits, so a request fails if it exceeds any applicable limit. When you exceed a limit, the request returns a `429 - TOO_MANY_REQUESTS` and the error message names the limit, scope, and value. **Most rate limits can be adjusted upon request.** If you need higher limits, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. > [!NOTE] > > Indexes built on [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) aren't subject to read unit limits for query, fetch, list, and full-text search operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) guide. ## Monthly usage limits [Read units](/guides/cost/understand-cost#read-units) and [write units](/guides/cost/understand-cost#write-units) measure resource consumption. To check your current usage, see [Download a usage report](/admin/billing/download-usage-report). | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | Read units per month per org | 1,000,000 | 2,000,000 | Unlimited | Unlimited | | Write units per month per org | 2,000,000 | 5,000,000 | Unlimited | Unlimited | | Embedding tokens per month per model | 5,000,000 | 10,000,000 | Unlimited | Unlimited | | `gemini-embedding-2` embedding tokens per month | Not available | 10,000,000 | Unlimited | Unlimited | > [!NOTE] > > From November 4 through December 31, 2026, Starter orgs get 10,000,000 embedding tokens per month per model, and Builder orgs get 20,000,000. Allowances return to the values in the table on January 1, 2027. Monthly rerank request limits vary by model: | Reranking model | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | `cohere-rerank-4-fast` | Not available | Not available | Unlimited | Unlimited | | `bge-reranker-v2-m3` | 500 | 1,000 | Unlimited | Unlimited | | `pinecone-rerank-v0` | 500 | Not available | Unlimited | Unlimited | Reaching a monthly usage limit returns a `429 - TOO_MANY_REQUESTS`. [Upgrade your plan](/admin/billing/upgrade-billing-plan) to continue. > [accordion] Example error > > ``` > Request failed. You've reached your read unit limit for the current month. > To continue reading data, upgrade your plan. > ``` ## Data operation throughput limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | Upsert size per second per namespace | 50 MB | 50 MB | 50 MB | 50 MB | | Query read units per second per namespace | 2,000 | 2,000 | 2,000 | 2,000 | | Query read units per second per index | 2,000 | 2,000 | 2,000 | 2,000 | | Query requests per second per namespace | 100 | 100 | 100 | 100 | | Update records per second per namespace | 100 | 100 | 100 | 100 | | Update requests per second per namespace | 100 | 100 | 100 | 100 | | Update by metadata requests per second per namespace | 20 | 20 | 20 | 20 | | Update by metadata requests per second per index | 500 | 500 | 500 | 500 | | Upsert requests per second per namespace | 100 | 100 | 100 | 100 | | Fetch requests per second per index | 100 | 100 | 100 | 100 | | List requests per second per index | 200 | 200 | 200 | 200 | | Describe index stats requests per second per index | 100 | 100 | 100 | 100 | | Delete requests per second per namespace | 100 | 100 | 100 | 100 | | Delete records per second per namespace | 5,000 | 5,000 | 5,000 | 5,000 | | Delete records per second per index | 5,000 | 5,000 | 5,000 | 5,000 | | Delete by metadata requests per second per namespace | 20 | 20 | 20 | 20 | | Delete by metadata requests per second per index | 500 | 500 | 500 | 500 | The per-namespace and per-index query read unit limits are enforced separately. At the defaults they're equal, so the namespace limit only matters once the index limit is raised. When you ask Support for a higher read limit, ask for both, or each namespace stays capped at its current limit. Exceeding a per-second throughput limit returns a `429 - TOO_MANY_REQUESTS`. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic), pace your requests, consider [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) (which aren't subject to per-second read limits) for high-throughput reads, or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) to raise a limit. > [accordion] Example 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. > ``` ## Model throughput limits Per-minute token limits for embedding models: | 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 | | `gemini-embedding-2` | Passage | Not available | 250,000 | 2,000,000 | 2,000,000 | | | Query | Not available | 50,000 | 250,000 | 250,000 | | `text-embedding-3-small` | Passage | 250,000 | 250,000 | 2,000,000 | 2,000,000 | | | Query | 50,000 | 50,000 | 250,000 | 250,000 | | `text-embedding-3-large` | Passage | 250,000 | 250,000 | 2,000,000 | 2,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 | Per-minute request limits for reranking models: | Reranking model | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | `cohere-rerank-4-fast` | Not available | Not available | 300 | 300 | | `bge-reranker-v2-m3` | 60 | 60 | 60 | 60 | | `pinecone-rerank-v0` | 60 | Not available | 60 | 60 | Reaching a per-minute model limit returns a `429 - TOO_MANY_REQUESTS`. [Upgrade your plan](/admin/billing/upgrade-billing-plan) to increase it, or [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). > [accordion] Example 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. > ``` ## Inference request limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | Inference requests per second per project | 100 | 100 | 100 | 100 | | Inference requests per minute per project | 2,000 | 2,000 | 2,000 | 2,000 | These limits apply per project across all models. Every inference request counts toward them, including requests that a [per-minute token limit](#model-throughput-limits) then rejects. Exceeding the per-second or per-minute limit returns a `429 - TOO_MANY_REQUESTS`. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle it. > [accordion] Example error > > ``` > Request failed. You've reached the max inference requests per second () for the current project. > ``` > > The message names the per-second or per-minute limit, whichever you exceeded. # Pinecone API errors Source: https://docs.pinecone.io/reference/api/errors Look up the HTTP status codes the Pinecone API returns, plus the causes and fixes for common Pinecone API and SDK error messages. Look up an [HTTP status code](#http-status-codes), or find an exact error message under [Index creation errors](#index-creation-errors) or [Outdated Python SDK errors](#outdated-python-sdk-errors). For handling errors in production, see [Error handling](/guides/production/error-handling). ## HTTP status codes 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. ### 200 - OK The request succeeded. ### 201 - CREATED The request succeeded and a new resource was created. ### 202 - ACCEPTED The request was accepted, but the operation isn't complete yet. For example, deleting an index returns `202` while the deletion is still in progress. ### 204 - NO CONTENT The request succeeded, and there's no response body 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](/admin/projects/projects-overview#api-keys). ### 402 - PAYMENT REQUIRED The request failed due to delinquent payment or account deactivation for non-payment. See [Account deactivation for non-payment](/admin/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/indexes/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. ## Index creation errors ### Missing spec argument ```console theme={null} TypeError: Pinecone.create_index() missing 1 required positional argument: 'spec' ``` Python SDK versions 3.0.0 to 9.x require a `spec` argument in `create_index()`. Pass one to set the index's cloud and region: ```python Python theme={null} from pinecone import Pinecone, 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"), ) ``` In Python SDK 10, `spec` is optional and new indexes default to AWS `us-east-1`. For current syntax, see [Create an index](/guides/indexes/create-an-index). ### Serverless index limit reached ```console theme={null} Request failed. You've reached the max serverless indexes allowed in project PROJECT_NAME (LIMIT). Use namespaces to partition your data into logical groups, or upgrade your plan to add more serverless indexes. ``` The API returns this with status `403` when the project already has as many serverless indexes as your plan allows. For the limit on each plan, see [Object limits](/reference/api/database-limits/object-limits). To fix it, do one of the following: * [Delete indexes](/guides/indexes/manage-indexes#delete-an-index) you no longer need. * Store data in [namespaces](/guides/data/implement-multitenancy) within one index instead of creating separate indexes. * [Upgrade your plan](/admin/billing/upgrade-billing-plan). ## Outdated Python SDK errors These errors come from code written for Python SDK versions earlier than 3.0.0, or from having the deprecated `pinecone-client` package installed. ### Pinecone has no attribute init ```console theme={null} AttributeError: module 'pinecone' has no attribute 'init' ``` In Python SDK 5.0.0 and later, the message reads: ```console theme={null} AttributeError: init is no longer a top-level attribute of the pinecone package. Please create an instance of the Pinecone class instead. ``` The code calls `pinecone.init()`, which was removed in version 3.0.0. Create a client instance instead. It doesn't take an environment, only an API key: ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` The same applies to other former top-level functions, such as `pinecone.create_index()` and `pinecone.list_indexes()`. Call them on the client instance instead. ### Cannot import name Pinecone ```console theme={null} ImportError: cannot import name 'Pinecone' from 'pinecone' ``` The installed SDK is earlier than 3.0.0, or the deprecated `pinecone-client` package is installed alongside `pinecone`. The Python SDK package was renamed from `pinecone-client` to `pinecone`, and having both installed causes conflicts. Remove the old package and upgrade: ```shell Shell theme={null} pip uninstall pinecone-client pip install --upgrade pinecone ``` ### Controller hostname not found ```console theme={null} Failed to resolve 'controller.us-west-2.pinecone.io' controller.us-west-2-aws.pinecone.io not found Request failed to reach Pinecone while calling https://controller.us-west-2.pinecone.io/actions/whoami ``` SDK versions earlier than 3.0.0 send requests to environment-specific `controller` hostnames. Current SDKs use `https://api.pinecone.io`. Upgrade the SDK, then update your code as described in [Pinecone has no attribute init](#pinecone-has-no-attribute-init): ```shell Shell theme={null} pip install --upgrade pinecone ``` # 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. > [!NOTE] > > [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: > [card] [CLI](/reference/cli/overview) > [card] [Python SDK](/reference/sdks/python/overview) > [card] [Node.js SDK](/reference/sdks/node/overview) > [card] [Java SDK](/reference/sdks/java/overview) > [card] [Go SDK](/reference/sdks/go/overview) ## Inference Use the Inference API to generate vector embeddings and rerank results using [embedding models](/guides/indexes/index-configuration#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-results) and [Generate vectors](/reference/api/latest/inference/generate-vectors) 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: > [card] [Python SDK](/reference/sdks/python/overview) > [card] [Node.js SDK](/reference/sdks/node/overview) > [card] [Java SDK](/reference/sdks/java/overview) > [card] [Go SDK](/reference/sdks/go/overview) # 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. ## Upserts * Pinecone is eventually consistent, so there can be a slight delay before [upserted records](/guides/data/upsert-data) are available to query. After upserting records, use the [Get index stats](/reference/api/latest/data-plane/describeindexstats) operation to check whether 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/indexes/index-data-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 don't support sparse vectors. ## Metadata * Null metadata values aren't supported. Instead of setting a key to `null`, remove the key from the metadata payload. * Nested JSON objects aren't supported. ## Serverless indexes Serverless indexes don't support the following features: * [Filtering index statistics by metadata](/reference/api/latest/data-plane/describeindexstats) * [Private endpoints](/guides/production/configure-private-endpoints) * This feature is available on AWS only. # Pinecone API versioning Source: https://docs.pinecone.io/reference/api/versioning Learn how Pinecone versions its APIs by release date, how long each stable version is supported, and how to set the X-Pinecone-Api-Version header. 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: ![](https://mintcdn.com/pinecone/9qvQp5nU6duJvusQ/images/api-versioning.png?fit=max\&auto=format\&n=9qvQp5nU6duJvusQ\&q=85\&s=be4366853edee83e003c3863e31fa1ce) ## Specify an API version > [!WARNING] > > 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-07`) 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-07" ``` 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 [changelog](/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](/admin/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](/admin/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" ``` > [!WARNING] > > 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 > [!NOTE] > > 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" ``` > [!NOTE] > > 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). > [!NOTE] > > `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 > [accordion] pc login (Authenticate via user login) > > **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" > ``` > > > [!NOTE] > > > > This is an alias for `pc auth login`. Both commands perform the same operation. > [accordion] pc logout (Clear credentials / log out) > > **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 > ``` > > > [!NOTE] > > > > 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. > [accordion] pc target (Set target organization and project) > > **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 > ``` > [accordion] pc version (Show CLI version) > > **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 > ``` > [accordion] pc whoami (Show current user) > > **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 > ``` > > > [!NOTE] > > > > This is an alias for `pc auth whoami`. Both commands perform the same operation. ### Authentication > [accordion] pc auth clear (Clear specific credentials) > > **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 > ``` > > > [!NOTE] > > > > 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`. > [accordion] pc auth configure (Configure service account or API key) > > **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 > ``` > > > [!NOTE] > > > > `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). > [accordion] pc auth local-keys list (List managed keys) > > **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 > ``` > [accordion] pc auth local-keys prune (Delete managed keys) > > **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 > ``` > > > [!NOTE] > > > > This deletes keys from both local storage and Pinecone servers. Use `--dry-run` to preview before committing. > [accordion] pc auth login (Authenticate via user login) > > **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 > ``` > > > [!NOTE] > > > > 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`. > [accordion] pc auth logout (Clear authentication credentials) > > **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 > ``` > > > [!NOTE] > > > > 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. > [accordion] pc auth status (Show authentication status) > > **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 > ``` > [accordion] pc auth whoami (Show current user information) > > **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 > ``` > > > [!NOTE] > > > > This command does the same thing as `pc whoami`. ### Indexes > [accordion] pc index configure (Update index configuration) > > **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 > ``` > > > [!NOTE] > > > > Configuration changes may take some time to take effect. > [accordion] pc index create (Create a new index) > > **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 > ``` > > > [!NOTE] > > > > For a list of valid regions for a serverless index, see [Create a serverless index](/guides/indexes/create-an-index). > [accordion] pc index delete (Delete 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 > ``` > > > [!NOTE] > > > > This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. > [accordion] pc index describe (Show index details) > > **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 > ``` > [accordion] pc index stats (Show index statistics) > > **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 > ``` > [accordion] pc index list (List all indexes) > > **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 > [accordion] pc index namespace create (Create a namespace) > > **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 > ``` > [accordion] pc index namespace delete (Delete a namespace) > > **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 > ``` > > > [!WARNING] > > > > Deleting a namespace removes all vectors in that namespace. This operation cannot be undone. > [accordion] pc index namespace describe (Show namespace details) > > **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 > ``` > [accordion] pc index namespace list (List namespaces) > > **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 > [accordion] pc index vector delete (Delete 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 > ``` > > > [!NOTE] > > > > 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. > > > [!WARNING] > > > > Vector deletion is permanent and cannot be undone. > [accordion] pc index vector fetch (Fetch vectors by ID or filter) > > **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 > ``` > > > [!NOTE] > > > > Use either `--ids` or `--filter`, not both. When using `--ids`, pagination flags are not applicable. > [accordion] pc index vector list (List vector IDs) > > **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 > ``` > [accordion] pc index vector query (Query vectors) > > **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 > ``` > > > [!NOTE] > > > > Use `--id`, `--vector`, or sparse vectors (`--sparse-indices` and `--sparse-values`) to specify what to query against. These options are mutually exclusive. > [accordion] pc index vector update (Update vectors) > > **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"}' > ``` > > > [!NOTE] > > > > Use either `--id` for single vector updates or `--filter` for bulk updates. These options are mutually exclusive. > [accordion] pc index vector upsert (Upsert vectors) > > **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 > ``` > > > [!NOTE] > > > > **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 > [accordion] pc index record search (Search records in an index) > > **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..."} > ``` > [accordion] pc index record upsert (Upsert records into an integrated index) > > **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 > [accordion] pc index collection create (Create a collection from a pod-based index) > > **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 > ``` > [accordion] pc index collection delete (Delete a collection) > > **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 > ``` > > > [!NOTE] > > > > This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. > [accordion] pc index collection describe (Describe a collection by name) > > **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 > ``` > [accordion] pc index collection list (List collections in your project) > > **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 > [accordion] pc index backup create (Create a backup) > > **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 > ``` > [accordion] pc index backup delete (Delete a backup) > > **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 > ``` > > > [!NOTE] > > > > This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. > > > [!WARNING] > > > > Backup deletion is permanent and cannot be undone. > [accordion] pc index backup describe (Show backup details) > > **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 > ``` > [accordion] pc index backup list (List backups) > > **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 > ``` > [accordion] pc index restore (Restore an index from a backup) > > **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 > ``` > [accordion] pc index restore describe (Show restore job details) > > **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 > ``` > [accordion] pc index restore list (List restore jobs) > > **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 > [accordion] pc index import start (Start an import from a storage URI) > > **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 > ``` > [accordion] pc index import describe (Describe an import operation) > > **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 > ``` > [accordion] pc index import list (List import operations for an index) > > **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 - > ``` > [accordion] pc index import cancel (Cancel an in-progress import operation) > > **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 > [accordion] pc project create (Create a new project) > > **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" > ``` > [accordion] pc project delete (Delete a 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 > ``` > > > [!NOTE] > > > > 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. > [accordion] pc project describe (Show project details) > > **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 > ``` > [accordion] pc project list (List all projects) > > **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 > ``` > [accordion] pc project update (Update project settings) > > **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 > [accordion] pc organization delete (Delete an organization) > > **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 > ``` > > > [!NOTE] > > > > 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. > [accordion] pc organization describe (Show organization details) > > **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 > ``` > [accordion] pc organization list (List organizations) > > **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 > ``` > [accordion] pc organization update (Update organization settings) > > **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 > [accordion] pc api-key create (Create a new API key) > > **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 > ``` > > > [!NOTE] > > > > API keys are scoped to a specific organization and project. > [accordion] pc api-key delete (Delete an API key) > > **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 > ``` > > > [!NOTE] > > > > Deletion is permanent. Applications using this key immediately lose access to Pinecone. > [accordion] pc api-key describe (Show API key details) > > **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 > ``` > > > [!NOTE] > > > > Does not display the actual key value. > [accordion] pc api-key list (List all API keys) > > **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 > ``` > > > [!NOTE] > > > > Does not display key values. > [accordion] pc api-key update (Update API key settings) > > **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 > ``` > > > [!NOTE] > > > > Cannot change the actual key. If you need a different key, create a new one. ### Config > [accordion] pc config list (List all configuration settings and their current values) > > **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 > ``` > [accordion] pc config get \ (Get the current value of a configuration setting) > > **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 > ``` > [accordion] pc config describe \ (Show detailed information about a configuration setting) > > **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 > ``` > [accordion] pc config set \ \ (Set a configuration value) > > **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 > ``` > [accordion] pc config unset \ (Reset a configuration value to its default) > > **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 > [tab] macOS (Homebrew) > > ```bash theme={null} > brew tap pinecone-io/tap > brew install pinecone-io/tap/pinecone > ``` > [tab] Other platforms > > 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" ``` > [!TIP] > > 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 Set the Pinecone CLI target context with pc target to control which organization and project your commands run against, including in CI/CD and JSON mode. 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. | > [!NOTE] > > `--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 > [!WARNING] > > 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 can't 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 don't 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). > [card] [Python SDK](/reference/sdks/python/overview) > [card] [Node.js SDK](/reference/sdks/node/overview) > [card] [Java SDK](/reference/sdks/java/overview) > [card] [Go SDK](/reference/sdks/go/overview) ## 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-07` | `2026-04` | `2025-10` | `2025-04` | `2025-01` | `2024-10` | `2024-07` | `2024-04` | | - | :- | :- | :- | :- | :- | :- | :- | :- | | [Python SDK](/reference/sdks/python/overview) | v10.x | 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) | v9.x | v8.x | v7.x | v6.x | v5.x | v4.x | v3.x | v2.x | | [Java SDK](/reference/sdks/java/overview) | Coming soon | Coming soon | v6.x | v5.x | v4.x | v3.x | v2.x | v1.x | | [Go SDK](/reference/sdks/go/overview) | v7.x | 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. > [!NOTE] > > 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 search, query, fetch, and list responses. For example, if a search 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/monitor-performance) or the organization-wide [Usage dashboard](/admin/billing/download-usage-report). ## Community SDKs Find community-contributed SDKs for Pinecone. These libraries aren't 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. > [!TIP] > > 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-07` | v7.x | | `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/v7/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/v7/pinecone@ ``` To check your SDK version, run the following command: ```shell theme={null} go list -u -m all | grep go-pinecone ``` ## Upgrade > [!WARNING] > > Before upgrading to `v7.0.0`, update all relevant code to account for the following breaking changes. See the [v7 migration guide](https://github.com/pinecone-io/go-pinecone/blob/main/guides/migration/v7.md) for before-and-after examples. > > * Pod-based index creation is removed. `CreatePodIndex` and `CreatePodIndexRequest` no longer exist, but existing pod-based indexes keep working. > * Enum constants are prefixed with their type name. For example, `Aws` is now `CloudAWS`, and `Cosine` is now `IndexMetricCosine`. > * `ListImports` takes a `*ListImportsRequest`, and `QueryByVectorIdRequest.SparseValues` is removed. > * `SourceCollection` and `Schema` on the legacy create requests now return an error. `ConfigureIndexParams.Embed` is replaced by `ConfigureIndexParams.Schema`. > * `Backup` field types changed, and some invalid requests now fail client-side. > > If you are upgrading from `v2` or earlier, also account for the `v3.0.0` 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 `v6` to `v7` means changing: ```go theme={null} // before import "github.com/pinecone-io/go-pinecone/v6/pinecone" // after import "github.com/pinecone-io/go-pinecone/v7/pinecone" ``` Apart from the module path, `v5.0.0` and `v6.0.0` are backward compatible with the release lines before them. `v7.0.0` targets API version `2026-07` and includes the breaking changes listed above. To stay on API version `2026-04`, keep using `v6`. 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/v7/pinecone@latest ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/admin/security/security-overview#api-keys) to initialize a client instance: ```Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v7/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](/admin/security/manage-rbac), initialize an `AdminClient` with [service account](/admin/organizations/manage-service-accounts) credentials instead: ```Go theme={null} package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v7/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) ``` > [!NOTE] > > 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)); ``` > [!TIP] > > 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) aren't currently instrumented. * **Bulk import operations** aren't yet instrumented. * **Server duration may be unavailable.** The `getServerDurationMs()` method returns `null` if the `x-pinecone-response-duration-ms` header isn't 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 don't 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 raised 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. > [!TIP] > > 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-10` | v6.x | | `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 6.3.0 # Gradle implementation "io.pinecone:pinecone-client:6.3.0" ``` Alternatively, you can download the standalone uberjar [pinecone-client-6.3.0-all.jar](https://repo1.maven.org/maven2/io/pinecone/pinecone-client/6.3.0/pinecone-client-6.3.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 > [!WARNING] > > Before upgrading from `v5.x` to `v6.x`, update code that passes enum values. Deletion protection, cloud, and import error mode now take strings, such as `"enabled"`, `"aws"`, and `"continue"`. For the full list of breaking changes, see the [`v6.0.0` release notes](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v6.0.0). 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 6.3.0 # Gradle implementation "io.pinecone:pinecone-client:6.3.0" ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/admin/security/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. > [!TIP] > > 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.js SDK requires Node.js 22 or later. Its type declarations support TypeScript 5.2 to 7.x. The SDK is for server-side use only. Running it in a browser exposes your API key, so call Pinecone from your backend instead. ## 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-07` | v9.x | | `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 `v9.0.0` targets API version `2026-07`. To stay on API version `2026-04`, keep using `v8`. The flat control methods, such as `pc.createIndex` and `pc.configureIndex`, still work in `v9` but are deprecated in favor of resource clients such as `pc.indexes`. > [!WARNING] > > Before upgrading to `v9.0.0`, update all relevant code to account for the following breaking changes. See the [v9 migration guide](https://github.com/pinecone-io/pinecone-ts-client/blob/main/guides/upgrading/v9-migration.md) for before-and-after examples. > > * Node.js 22 or later is required. > * `pc.preview` and the `Preview*` exports are removed. Document operations move to `index.documents`, where `index` comes from `pc.index({ name, namespace })` or `pc.index(name).namespace(namespace)`. Control operations move to resource clients such as `pc.indexes`. > * Pod-based index creation, legacy metadata-indexing schemas, and the `sourceCollection` and `sourceBackupId` creation options are rejected. Existing pod-based indexes keep working. To restore from a backup, use `pc.backups.createIndex(backupId, options)`. > * A top-level `embed` option when configuring an index is rejected. Update the semantic field through a `schema.fields` patch instead. > * Legacy index response properties such as `dimension`, `metric`, and `spec` are compatibility getters derived from `schema` and `deployment`. They are omitted when a response is spread or serialized, and can throw `Errors.PineconeIndexPropertyError` when there is no legacy equivalent. > * `NamespaceDescription.recordCount` and `sizeBytes` are now decimal strings, and `BackupModel.createdAt` is now a `Date`. > * Some generated type names are renamed or removed. For example, `BackupPaginationResponse` is now `BackupListPagination`. 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](/admin/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](/admin/security/manage-rbac), initialize an `AdminClient` with [service account](/admin/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. > [!NOTE] > > 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. > [!TIP] > > 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`. The base install includes the sync and [async](#async-requests) clients and the [gRPC](https://grpc.io/) data-plane client, so there are no extras to install. ## Requirements The Pinecone Python SDK requires Python 3.10 or later. It has been tested with CPython versions from 3.10 to 3.14. ## 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 | | :- | :- | | `2026-07` | v10.x | | `2026-04` | v9.x | | `2025-10` | v8.x | | `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 ``` To install a specific version of the Python SDK, run the following command: ```shell pip theme={null} # Install a specific version pip install pinecone== ``` SDK versions 8.x and earlier shipped gRPC and asyncio support as optional extras. To use them on those versions, install `"pinecone[grpc]=="` or `"pinecone[asyncio]=="`. To check your SDK version, run the following command: ```shell pip theme={null} pip show pinecone ``` > [!NOTE] > > 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's 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 > [!WARNING] > > 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 ``` ## Initialize Once installed, you can import the library and then use an [API key](/admin/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/indexes/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's disabled when set to `False`. It's 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 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 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/indexes/index-data-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. > [tab] Python SDK without gRPC > > When using the Python SDK without gRPC, to get good performance, it's 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 aren't 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) > ``` > [tab] Python SDK with gRPC > > When using the Python SDK with gRPC, 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 with the [Python SDK](/reference/sdks/python/overview), use the `upsert_from_dataframe` method. It upserts in batches (set the size with `batch_size`), retries failed requests, and performs especially well with data loaded from Parquet files. The dataframe needs `id` and `values` columns, plus an optional `metadata` column. ```Python Python theme={null} import pandas as pd from pinecone import Pinecone pc = Pinecone(api_key="API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/target-an-index index = pc.Index(host="INDEX_HOST") # To load a Parquet file instead, use pd.read_parquet("path/to/file.parquet") df = pd.DataFrame({ "id": ["A", "B", "C"], "values": [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6], [0.7, 0.8, 0.9]], "metadata": [{"genre": "drama"}, {"genre": "comedy"}, {"genre": "drama"}], }) index.upsert_from_dataframe(df, namespace="example-namespace", batch_size=500) ``` # 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 > [tab] Databricks platform > > 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.2.0/spark-pinecone-uberjar.jar > ``` > > > [!NOTE] > > > > Databricks platform users must use the Pinecone assembly jar listed above to ensure that the proper dependecies are installed. > > 3. Click **Install**. > [tab] Databricks on AWS > > 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.2.0/spark-pinecone-uberjar.jar > ``` > > 3. Click **Install**. > [tab] Databricks on GCP / Azure > > 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.2.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() } ``` > [!TIP] > > 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) # Pinecone API 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](/admin/security/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; 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", "disabled", null); } } ``` ```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: 2026-07" \ -d '{ "name": "docs-example", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "_values": { "type": "dense_vector", "dimension": 1536, "metric": "cosine" } } } }' ``` ## Add headers to an HTTP request All HTTP requests to Pinecone APIs must contain an `Api-Key` header that specifies a valid [API key](/admin/security/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: 2026-07" \ -d '{ "name": "docs-example", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "_values": { "type": "dense_vector", "dimension": 1536, "metric": "cosine" } } } }' ``` ## Troubleshooting > [accordion] Initialization errors due to outdated SDKs > > 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 overview Source: https://docs.pinecone.io/reference/api/database-limits Reference for Pinecone Database rate, object, operation, and identifier limits, plus known index and serverless limitations. This page describes the limits and known limitations for Pinecone Database. Each topic has its own reference page: * **[Rate limits](/reference/api/database-limits/rate-limits)**: request-per-second, monthly usage, and model throughput limits that vary by pricing plan, plus the `429` errors you get when you exceed them. * **[Object limits](/reference/api/database-limits/object-limits)**: the number or size of projects, users, indexes, namespaces, storage, backups, and collections allowed by plan. * **[Operation limits](/reference/api/database-limits/operation-limits)**: fixed batch-size limits for upsert, import, query, fetch, and delete, plus metadata filter limits. * **[Identifier limits](/reference/api/database-limits/identifier-limits)**: maximum length and allowed characters for organization, project, index, namespace, and record identifiers. * **[Known limitations](/reference/api/known-limitations)**: index and serverless caveats, such as upsert consistency and metadata rules. > [!NOTE] > > If a limit is blocking you, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. Many limits can be raised on request, and Support can often suggest a workaround for the ones that can't. # Identifier limits Source: https://docs.pinecone.io/reference/api/database-limits/identifier-limits Maximum length and allowed characters for Pinecone identifiers, including organization, project, index, namespace, and record names. An identifier is a string of characters used to identify "named" [objects in Pinecone](/guides/get-started/key-terms). The following Pinecone objects use strings as identifiers: | Object | Field | Max # characters | Allowed characters | | - | - | - | - | | [Organization](/guides/get-started/key-terms#organization) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Project](/guides/get-started/key-terms#project) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Index](/guides/get-started/key-terms#index) | `name` | 45 |
  • `a-z`, `0-9`, and `-`
  • Must be lowercase
  • Cannot start or end with `-`
  • Cannot be empty
| | [Namespace](/guides/get-started/key-terms#namespace) | `namespace` | 512 |
  • ASCII except `\0`
  • For the default namespace, use `""` (or `"__default__"`, in API versions `2025-04` and later)
| | [Namespace alias](/guides/data/namespace-aliases/overview) | `name` | 512 |
  • ASCII graphic characters
  • No spaces or `/ ? # % & = \ ; +`
  • `.`, `..`, and `__default__` are reserved
  • Must be unique in the index and can't match a namespace name
| | [Record](/guides/get-started/key-terms#record) | `id` | 512 |
  • ASCII except `\0`
  • Cannot be empty
| # Object limits Source: https://docs.pinecone.io/reference/api/database-limits/object-limits Limits on the number and size of Pinecone Database projects, indexes, namespaces, storage, backups, and collections, by plan. Object limits are restrictions on the number or size of objects in Pinecone. They vary based on [pricing plan](https://www.pinecone.io/pricing/). | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | Projects per organization | 1 | 5 | 20 | 100 | | Users per organization | 2 | 5 | Unlimited | Unlimited | | Serverless indexes per project 1 | 5 | 10 | 20 | 200 | | Serverless index storage per org | 2 GB | 10 GB | N/A | N/A | | Namespaces per serverless index | 100 | 1,000 | 100,000 | 1,000,000 | | Namespace aliases per serverless index | 1,000 | 1,000 | 1,000 | 1,000 | | Serverless backups per project | N/A | N/A | 500 | 1,000 | | 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/indexes/index-configuration#cloud-regions).\ When you exceed an object limit, API operations return a `403 - QUOTA_EXCEEDED`. [Upgrade your plan](/admin/billing/upgrade-billing-plan) to increase the limit. If a higher plan still doesn't cover what you need, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case, since most object limits can be raised on request. > [accordion] Example error > > ``` > Request failed. You've reached the max projects allowed in organization . > To add more projects, upgrade your plan. > ``` For the serverless storage limit, you can also [delete records](/guides/data/delete-data) to get back under it. > [!TIP] > > To stay under the serverless index limit, use [namespaces](/guides/indexes/create-an-index#namespaces) to partition data within a single index instead of creating multiple indexes. This can also improve query performance and lower costs by limiting searches to relevant data subsets. > [!NOTE] > > [Namespaces per serverless index](/reference/api/database-limits/object-limits) vary by plan (100 on Starter to 1,000,000 on Enterprise). Pinecone can accommodate more for specific use cases. If your application needs a higher limit, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). # Operation limits Source: https://docs.pinecone.io/reference/api/database-limits/operation-limits Fixed limits on Pinecone Database operations, including upsert, update, import, query, fetch, and delete batch sizes and metadata filter expressions. Operation limits are restrictions on the size, number, or other characteristics of operations in Pinecone. Operation limits are fixed and don't vary based on pricing plan. If one of these limits is blocking you, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. There's often a workaround. ## Upsert limits | Metric | Limit | | :- | :- | | Max [batch size](/guides/legacy/vectors-api/upsert-vectors#upsert-in-batches) for records with vectors | 1,000 records, up to 2 MB total | | Max batch size for records with text | 96 records | | Max documents per upsert request | 1,000, or 96 when the schema declares `embed` or `sparse_embed` | | 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](/guides/search/full-text-search/text-processing#tokens-and-analyzers) | 1,024 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 limit for text is lower because Pinecone converts that text to vectors at upsert time with [integrated embedding](/guides/indexes/index-data-overview#integrated-embedding), and 96 is the max batch size of the [hosted embedding models](/guides/indexes/index-configuration#embedding-models) doing the conversion. The 40 KB filterable metadata limit doesn't apply to `full_text_search` text fields. ## Update limits | Metric | Limit | | :- | :- | | Max documents per by-ID document update request | 1,000, or 96 when the schema declares `embed` or `sparse_embed` | | Max records per update-by-metadata request | 100,000 | ## Import limits > [!NOTE] > > If your import exceeds these limits, you'll get an error specifying the limit exceeded. See [Troubleshooting](/guides/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 doesn't apply to indexes with [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview). Bulk import supports indexes without a schema definition (Parquet files) and indexes with document schemas ([JSONL files](/guides/data/import-data#prepare-document-schema-files-jsonl)). Semantic-text (auto-embedded) fields aren't 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. > [!TIP] > > 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/legacy/vectors-api/fetch-vectors#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 returns 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 multitenancy](/guides/data/design-for-multitenancy). * **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 multitenancy](/guides/data/design-for-multitenancy#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. > [!TIP] > > 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. # Rate limits Source: https://docs.pinecone.io/reference/api/database-limits/rate-limits Request-per-second, monthly usage, and model throughput limits for Pinecone Database serverless indexes, and the 429 errors returned when you exceed them. Rate limits help protect your applications from misuse and maintain the health of our shared serverless infrastructure. They vary by [pricing plan](https://www.pinecone.io/pricing/) and apply to [serverless indexes](/guides/indexes/index-data-overview) only. Request-per-second limits are enforced per namespace or per index, as noted in the [Data operation throughput limits](#data-operation-throughput-limits) table, in addition to your read and write unit limits, so a request fails if it exceeds any applicable limit. When you exceed a limit, the request returns a `429 - TOO_MANY_REQUESTS` and the error message names the limit, scope, and value. **Most rate limits can be adjusted upon request.** If you need higher limits, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. > [!NOTE] > > Indexes built on [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) aren't subject to read unit limits for query, fetch, list, and full-text search operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) guide. ## Monthly usage limits [Read units](/guides/cost/understand-cost#read-units) and [write units](/guides/cost/understand-cost#write-units) measure resource consumption. To check your current usage, see [Download a usage report](/admin/billing/download-usage-report). | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | Read units per month per org | 1,000,000 | 2,000,000 | Unlimited | Unlimited | | Write units per month per org | 2,000,000 | 5,000,000 | Unlimited | Unlimited | | Embedding tokens per month per model | 5,000,000 | 10,000,000 | Unlimited | Unlimited | | `gemini-embedding-2` embedding tokens per month | Not available | 10,000,000 | Unlimited | Unlimited | > [!NOTE] > > From November 4 through December 31, 2026, Starter orgs get 10,000,000 embedding tokens per month per model, and Builder orgs get 20,000,000. Allowances return to the values in the table on January 1, 2027. Monthly rerank request limits vary by model: | Reranking model | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | `cohere-rerank-4-fast` | Not available | Not available | Unlimited | Unlimited | | `bge-reranker-v2-m3` | 500 | 1,000 | Unlimited | Unlimited | | `pinecone-rerank-v0` | 500 | Not available | Unlimited | Unlimited | Reaching a monthly usage limit returns a `429 - TOO_MANY_REQUESTS`. [Upgrade your plan](/admin/billing/upgrade-billing-plan) to continue. > [accordion] Example error > > ``` > Request failed. You've reached your read unit limit for the current month. > To continue reading data, upgrade your plan. > ``` ## Data operation throughput limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | Upsert size per second per namespace | 50 MB | 50 MB | 50 MB | 50 MB | | Query read units per second per namespace | 2,000 | 2,000 | 2,000 | 2,000 | | Query read units per second per index | 2,000 | 2,000 | 2,000 | 2,000 | | Query requests per second per namespace | 100 | 100 | 100 | 100 | | Update records per second per namespace | 100 | 100 | 100 | 100 | | Update requests per second per namespace | 100 | 100 | 100 | 100 | | Update by metadata requests per second per namespace | 20 | 20 | 20 | 20 | | Update by metadata requests per second per index | 500 | 500 | 500 | 500 | | Upsert requests per second per namespace | 100 | 100 | 100 | 100 | | Fetch requests per second per index | 100 | 100 | 100 | 100 | | List requests per second per index | 200 | 200 | 200 | 200 | | Describe index stats requests per second per index | 100 | 100 | 100 | 100 | | Delete requests per second per namespace | 100 | 100 | 100 | 100 | | Delete records per second per namespace | 5,000 | 5,000 | 5,000 | 5,000 | | Delete records per second per index | 5,000 | 5,000 | 5,000 | 5,000 | | Delete by metadata requests per second per namespace | 20 | 20 | 20 | 20 | | Delete by metadata requests per second per index | 500 | 500 | 500 | 500 | The per-namespace and per-index query read unit limits are enforced separately. At the defaults they're equal, so the namespace limit only matters once the index limit is raised. When you ask Support for a higher read limit, ask for both, or each namespace stays capped at its current limit. Exceeding a per-second throughput limit returns a `429 - TOO_MANY_REQUESTS`. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic), pace your requests, consider [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) (which aren't subject to per-second read limits) for high-throughput reads, or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) to raise a limit. > [accordion] Example 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. > ``` ## Model throughput limits Per-minute token limits for embedding models: | 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 | | `gemini-embedding-2` | Passage | Not available | 250,000 | 2,000,000 | 2,000,000 | | | Query | Not available | 50,000 | 250,000 | 250,000 | | `text-embedding-3-small` | Passage | 250,000 | 250,000 | 2,000,000 | 2,000,000 | | | Query | 50,000 | 50,000 | 250,000 | 250,000 | | `text-embedding-3-large` | Passage | 250,000 | 250,000 | 2,000,000 | 2,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 | Per-minute request limits for reranking models: | Reranking model | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | `cohere-rerank-4-fast` | Not available | Not available | 300 | 300 | | `bge-reranker-v2-m3` | 60 | 60 | 60 | 60 | | `pinecone-rerank-v0` | 60 | Not available | 60 | 60 | Reaching a per-minute model limit returns a `429 - TOO_MANY_REQUESTS`. [Upgrade your plan](/admin/billing/upgrade-billing-plan) to increase it, or [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). > [accordion] Example 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. > ``` ## Inference request limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | Inference requests per second per project | 100 | 100 | 100 | 100 | | Inference requests per minute per project | 2,000 | 2,000 | 2,000 | 2,000 | These limits apply per project across all models. Every inference request counts toward them, including requests that a [per-minute token limit](#model-throughput-limits) then rejects. Exceeding the per-second or per-minute limit returns a `429 - TOO_MANY_REQUESTS`. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle it. > [accordion] Example error > > ``` > Request failed. You've reached the max inference requests per second () for the current project. > ``` > > The message names the per-second or per-minute limit, whichever you exceeded. # Pinecone API errors Source: https://docs.pinecone.io/reference/api/errors Look up the HTTP status codes the Pinecone API returns, plus the causes and fixes for common Pinecone API and SDK error messages. Look up an [HTTP status code](#http-status-codes), or find an exact error message under [Index creation errors](#index-creation-errors) or [Outdated Python SDK errors](#outdated-python-sdk-errors). For handling errors in production, see [Error handling](/guides/production/error-handling). ## HTTP status codes 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. ### 200 - OK The request succeeded. ### 201 - CREATED The request succeeded and a new resource was created. ### 202 - ACCEPTED The request was accepted, but the operation isn't complete yet. For example, deleting an index returns `202` while the deletion is still in progress. ### 204 - NO CONTENT The request succeeded, and there's no response body 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](/admin/projects/projects-overview#api-keys). ### 402 - PAYMENT REQUIRED The request failed due to delinquent payment or account deactivation for non-payment. See [Account deactivation for non-payment](/admin/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/indexes/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. ## Index creation errors ### Missing spec argument ```console theme={null} TypeError: Pinecone.create_index() missing 1 required positional argument: 'spec' ``` Python SDK versions 3.0.0 to 9.x require a `spec` argument in `create_index()`. Pass one to set the index's cloud and region: ```python Python theme={null} from pinecone import Pinecone, 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"), ) ``` In Python SDK 10, `spec` is optional and new indexes default to AWS `us-east-1`. For current syntax, see [Create an index](/guides/indexes/create-an-index). ### Serverless index limit reached ```console theme={null} Request failed. You've reached the max serverless indexes allowed in project PROJECT_NAME (LIMIT). Use namespaces to partition your data into logical groups, or upgrade your plan to add more serverless indexes. ``` The API returns this with status `403` when the project already has as many serverless indexes as your plan allows. For the limit on each plan, see [Object limits](/reference/api/database-limits/object-limits). To fix it, do one of the following: * [Delete indexes](/guides/indexes/manage-indexes#delete-an-index) you no longer need. * Store data in [namespaces](/guides/data/implement-multitenancy) within one index instead of creating separate indexes. * [Upgrade your plan](/admin/billing/upgrade-billing-plan). ## Outdated Python SDK errors These errors come from code written for Python SDK versions earlier than 3.0.0, or from having the deprecated `pinecone-client` package installed. ### Pinecone has no attribute init ```console theme={null} AttributeError: module 'pinecone' has no attribute 'init' ``` In Python SDK 5.0.0 and later, the message reads: ```console theme={null} AttributeError: init is no longer a top-level attribute of the pinecone package. Please create an instance of the Pinecone class instead. ``` The code calls `pinecone.init()`, which was removed in version 3.0.0. Create a client instance instead. It doesn't take an environment, only an API key: ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` The same applies to other former top-level functions, such as `pinecone.create_index()` and `pinecone.list_indexes()`. Call them on the client instance instead. ### Cannot import name Pinecone ```console theme={null} ImportError: cannot import name 'Pinecone' from 'pinecone' ``` The installed SDK is earlier than 3.0.0, or the deprecated `pinecone-client` package is installed alongside `pinecone`. The Python SDK package was renamed from `pinecone-client` to `pinecone`, and having both installed causes conflicts. Remove the old package and upgrade: ```shell Shell theme={null} pip uninstall pinecone-client pip install --upgrade pinecone ``` ### Controller hostname not found ```console theme={null} Failed to resolve 'controller.us-west-2.pinecone.io' controller.us-west-2-aws.pinecone.io not found Request failed to reach Pinecone while calling https://controller.us-west-2.pinecone.io/actions/whoami ``` SDK versions earlier than 3.0.0 send requests to environment-specific `controller` hostnames. Current SDKs use `https://api.pinecone.io`. Upgrade the SDK, then update your code as described in [Pinecone has no attribute init](#pinecone-has-no-attribute-init): ```shell Shell theme={null} pip install --upgrade pinecone ``` # 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. > [!NOTE] > > [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: > [card] [CLI](/reference/cli/overview) > [card] [Python SDK](/reference/sdks/python/overview) > [card] [Node.js SDK](/reference/sdks/node/overview) > [card] [Java SDK](/reference/sdks/java/overview) > [card] [Go SDK](/reference/sdks/go/overview) ## Inference Use the Inference API to generate vector embeddings and rerank results using [embedding models](/guides/indexes/index-configuration#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-results) and [Generate vectors](/reference/api/latest/inference/generate-vectors) 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: > [card] [Python SDK](/reference/sdks/python/overview) > [card] [Node.js SDK](/reference/sdks/node/overview) > [card] [Java SDK](/reference/sdks/java/overview) > [card] [Go SDK](/reference/sdks/go/overview) # 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. ## Upserts * Pinecone is eventually consistent, so there can be a slight delay before [upserted records](/guides/data/upsert-data) are available to query. After upserting records, use the [Get index stats](/reference/api/latest/data-plane/describeindexstats) operation to check whether 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/indexes/index-data-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 don't support sparse vectors. ## Metadata * Null metadata values aren't supported. Instead of setting a key to `null`, remove the key from the metadata payload. * Nested JSON objects aren't supported. ## Serverless indexes Serverless indexes don't support the following features: * [Filtering index statistics by metadata](/reference/api/latest/data-plane/describeindexstats) * [Private endpoints](/guides/production/configure-private-endpoints) * This feature is available on AWS only. # Pinecone API versioning Source: https://docs.pinecone.io/reference/api/versioning Learn how Pinecone versions its APIs by release date, how long each stable version is supported, and how to set the X-Pinecone-Api-Version header. 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: ![](https://mintcdn.com/pinecone/9qvQp5nU6duJvusQ/images/api-versioning.png?fit=max\&auto=format\&n=9qvQp5nU6duJvusQ\&q=85\&s=be4366853edee83e003c3863e31fa1ce) ## Specify an API version > [!WARNING] > > 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-07`) 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-07" ``` 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 [changelog](/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](/admin/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](/admin/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" ``` > [!WARNING] > > 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 > [!NOTE] > > 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" ``` > [!NOTE] > > 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). > [!NOTE] > > `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 > [accordion] pc login (Authenticate via user login) > > **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" > ``` > > > [!NOTE] > > > > This is an alias for `pc auth login`. Both commands perform the same operation. > [accordion] pc logout (Clear credentials / log out) > > **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 > ``` > > > [!NOTE] > > > > 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. > [accordion] pc target (Set target organization and project) > > **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 > ``` > [accordion] pc version (Show CLI version) > > **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 > ``` > [accordion] pc whoami (Show current user) > > **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 > ``` > > > [!NOTE] > > > > This is an alias for `pc auth whoami`. Both commands perform the same operation. ### Authentication > [accordion] pc auth clear (Clear specific credentials) > > **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 > ``` > > > [!NOTE] > > > > 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`. > [accordion] pc auth configure (Configure service account or API key) > > **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 > ``` > > > [!NOTE] > > > > `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). > [accordion] pc auth local-keys list (List managed keys) > > **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 > ``` > [accordion] pc auth local-keys prune (Delete managed keys) > > **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 > ``` > > > [!NOTE] > > > > This deletes keys from both local storage and Pinecone servers. Use `--dry-run` to preview before committing. > [accordion] pc auth login (Authenticate via user login) > > **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 > ``` > > > [!NOTE] > > > > 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`. > [accordion] pc auth logout (Clear authentication credentials) > > **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 > ``` > > > [!NOTE] > > > > 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. > [accordion] pc auth status (Show authentication status) > > **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 > ``` > [accordion] pc auth whoami (Show current user information) > > **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 > ``` > > > [!NOTE] > > > > This command does the same thing as `pc whoami`. ### Indexes > [accordion] pc index configure (Update index configuration) > > **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 > ``` > > > [!NOTE] > > > > Configuration changes may take some time to take effect. > [accordion] pc index create (Create a new index) > > **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 > ``` > > > [!NOTE] > > > > For a list of valid regions for a serverless index, see [Create a serverless index](/guides/indexes/create-an-index). > [accordion] pc index delete (Delete 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 > ``` > > > [!NOTE] > > > > This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. > [accordion] pc index describe (Show index details) > > **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 > ``` > [accordion] pc index stats (Show index statistics) > > **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 > ``` > [accordion] pc index list (List all indexes) > > **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 > [accordion] pc index namespace create (Create a namespace) > > **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 > ``` > [accordion] pc index namespace delete (Delete a namespace) > > **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 > ``` > > > [!WARNING] > > > > Deleting a namespace removes all vectors in that namespace. This operation cannot be undone. > [accordion] pc index namespace describe (Show namespace details) > > **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 > ``` > [accordion] pc index namespace list (List namespaces) > > **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 > [accordion] pc index vector delete (Delete 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 > ``` > > > [!NOTE] > > > > 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. > > > [!WARNING] > > > > Vector deletion is permanent and cannot be undone. > [accordion] pc index vector fetch (Fetch vectors by ID or filter) > > **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 > ``` > > > [!NOTE] > > > > Use either `--ids` or `--filter`, not both. When using `--ids`, pagination flags are not applicable. > [accordion] pc index vector list (List vector IDs) > > **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 > ``` > [accordion] pc index vector query (Query vectors) > > **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 > ``` > > > [!NOTE] > > > > Use `--id`, `--vector`, or sparse vectors (`--sparse-indices` and `--sparse-values`) to specify what to query against. These options are mutually exclusive. > [accordion] pc index vector update (Update vectors) > > **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"}' > ``` > > > [!NOTE] > > > > Use either `--id` for single vector updates or `--filter` for bulk updates. These options are mutually exclusive. > [accordion] pc index vector upsert (Upsert vectors) > > **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 > ``` > > > [!NOTE] > > > > **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 > [accordion] pc index record search (Search records in an index) > > **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..."} > ``` > [accordion] pc index record upsert (Upsert records into an integrated index) > > **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 > [accordion] pc index collection create (Create a collection from a pod-based index) > > **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 > ``` > [accordion] pc index collection delete (Delete a collection) > > **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 > ``` > > > [!NOTE] > > > > This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. > [accordion] pc index collection describe (Describe a collection by name) > > **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 > ``` > [accordion] pc index collection list (List collections in your project) > > **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 > [accordion] pc index backup create (Create a backup) > > **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 > ``` > [accordion] pc index backup delete (Delete a backup) > > **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 > ``` > > > [!NOTE] > > > > This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. > > > [!WARNING] > > > > Backup deletion is permanent and cannot be undone. > [accordion] pc index backup describe (Show backup details) > > **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 > ``` > [accordion] pc index backup list (List backups) > > **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 > ``` > [accordion] pc index restore (Restore an index from a backup) > > **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 > ``` > [accordion] pc index restore describe (Show restore job details) > > **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 > ``` > [accordion] pc index restore list (List restore jobs) > > **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 > [accordion] pc index import start (Start an import from a storage URI) > > **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 > ``` > [accordion] pc index import describe (Describe an import operation) > > **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 > ``` > [accordion] pc index import list (List import operations for an index) > > **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 - > ``` > [accordion] pc index import cancel (Cancel an in-progress import operation) > > **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 > [accordion] pc project create (Create a new project) > > **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" > ``` > [accordion] pc project delete (Delete a 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 > ``` > > > [!NOTE] > > > > 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. > [accordion] pc project describe (Show project details) > > **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 > ``` > [accordion] pc project list (List all projects) > > **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 > ``` > [accordion] pc project update (Update project settings) > > **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 > [accordion] pc organization delete (Delete an organization) > > **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 > ``` > > > [!NOTE] > > > > 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. > [accordion] pc organization describe (Show organization details) > > **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 > ``` > [accordion] pc organization list (List organizations) > > **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 > ``` > [accordion] pc organization update (Update organization settings) > > **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 > [accordion] pc api-key create (Create a new API key) > > **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 > ``` > > > [!NOTE] > > > > API keys are scoped to a specific organization and project. > [accordion] pc api-key delete (Delete an API key) > > **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 > ``` > > > [!NOTE] > > > > Deletion is permanent. Applications using this key immediately lose access to Pinecone. > [accordion] pc api-key describe (Show API key details) > > **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 > ``` > > > [!NOTE] > > > > Does not display the actual key value. > [accordion] pc api-key list (List all API keys) > > **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 > ``` > > > [!NOTE] > > > > Does not display key values. > [accordion] pc api-key update (Update API key settings) > > **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 > ``` > > > [!NOTE] > > > > Cannot change the actual key. If you need a different key, create a new one. ### Config > [accordion] pc config list (List all configuration settings and their current values) > > **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 > ``` > [accordion] pc config get \ (Get the current value of a configuration setting) > > **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 > ``` > [accordion] pc config describe \ (Show detailed information about a configuration setting) > > **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 > ``` > [accordion] pc config set \ \ (Set a configuration value) > > **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 > ``` > [accordion] pc config unset \ (Reset a configuration value to its default) > > **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 > [tab] macOS (Homebrew) > > ```bash theme={null} > brew tap pinecone-io/tap > brew install pinecone-io/tap/pinecone > ``` > [tab] Other platforms > > 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" ``` > [!TIP] > > 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 Set the Pinecone CLI target context with pc target to control which organization and project your commands run against, including in CI/CD and JSON mode. 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. | > [!NOTE] > > `--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 > [!WARNING] > > 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 can't 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 don't 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). > [card] [Python SDK](/reference/sdks/python/overview) > [card] [Node.js SDK](/reference/sdks/node/overview) > [card] [Java SDK](/reference/sdks/java/overview) > [card] [Go SDK](/reference/sdks/go/overview) ## 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-07` | `2026-04` | `2025-10` | `2025-04` | `2025-01` | `2024-10` | `2024-07` | `2024-04` | | - | :- | :- | :- | :- | :- | :- | :- | :- | | [Python SDK](/reference/sdks/python/overview) | v10.x | 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) | v9.x | v8.x | v7.x | v6.x | v5.x | v4.x | v3.x | v2.x | | [Java SDK](/reference/sdks/java/overview) | Coming soon | Coming soon | v6.x | v5.x | v4.x | v3.x | v2.x | v1.x | | [Go SDK](/reference/sdks/go/overview) | v7.x | 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. > [!NOTE] > > 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 search, query, fetch, and list responses. For example, if a search 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/monitor-performance) or the organization-wide [Usage dashboard](/admin/billing/download-usage-report). ## Community SDKs Find community-contributed SDKs for Pinecone. These libraries aren't 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. > [!TIP] > > 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-07` | v7.x | | `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/v7/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/v7/pinecone@ ``` To check your SDK version, run the following command: ```shell theme={null} go list -u -m all | grep go-pinecone ``` ## Upgrade > [!WARNING] > > Before upgrading to `v7.0.0`, update all relevant code to account for the following breaking changes. See the [v7 migration guide](https://github.com/pinecone-io/go-pinecone/blob/main/guides/migration/v7.md) for before-and-after examples. > > * Pod-based index creation is removed. `CreatePodIndex` and `CreatePodIndexRequest` no longer exist, but existing pod-based indexes keep working. > * Enum constants are prefixed with their type name. For example, `Aws` is now `CloudAWS`, and `Cosine` is now `IndexMetricCosine`. > * `ListImports` takes a `*ListImportsRequest`, and `QueryByVectorIdRequest.SparseValues` is removed. > * `SourceCollection` and `Schema` on the legacy create requests now return an error. `ConfigureIndexParams.Embed` is replaced by `ConfigureIndexParams.Schema`. > * `Backup` field types changed, and some invalid requests now fail client-side. > > If you are upgrading from `v2` or earlier, also account for the `v3.0.0` 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 `v6` to `v7` means changing: ```go theme={null} // before import "github.com/pinecone-io/go-pinecone/v6/pinecone" // after import "github.com/pinecone-io/go-pinecone/v7/pinecone" ``` Apart from the module path, `v5.0.0` and `v6.0.0` are backward compatible with the release lines before them. `v7.0.0` targets API version `2026-07` and includes the breaking changes listed above. To stay on API version `2026-04`, keep using `v6`. 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/v7/pinecone@latest ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/admin/security/security-overview#api-keys) to initialize a client instance: ```Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v7/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](/admin/security/manage-rbac), initialize an `AdminClient` with [service account](/admin/organizations/manage-service-accounts) credentials instead: ```Go theme={null} package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v7/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) ``` > [!NOTE] > > 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)); ``` > [!TIP] > > 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) aren't currently instrumented. * **Bulk import operations** aren't yet instrumented. * **Server duration may be unavailable.** The `getServerDurationMs()` method returns `null` if the `x-pinecone-response-duration-ms` header isn't 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 don't 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 raised 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. > [!TIP] > > 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-10` | v6.x | | `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 6.3.0 # Gradle implementation "io.pinecone:pinecone-client:6.3.0" ``` Alternatively, you can download the standalone uberjar [pinecone-client-6.3.0-all.jar](https://repo1.maven.org/maven2/io/pinecone/pinecone-client/6.3.0/pinecone-client-6.3.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 > [!WARNING] > > Before upgrading from `v5.x` to `v6.x`, update code that passes enum values. Deletion protection, cloud, and import error mode now take strings, such as `"enabled"`, `"aws"`, and `"continue"`. For the full list of breaking changes, see the [`v6.0.0` release notes](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v6.0.0). 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 6.3.0 # Gradle implementation "io.pinecone:pinecone-client:6.3.0" ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/admin/security/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. > [!TIP] > > 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.js SDK requires Node.js 22 or later. Its type declarations support TypeScript 5.2 to 7.x. The SDK is for server-side use only. Running it in a browser exposes your API key, so call Pinecone from your backend instead. ## 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-07` | v9.x | | `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 `v9.0.0` targets API version `2026-07`. To stay on API version `2026-04`, keep using `v8`. The flat control methods, such as `pc.createIndex` and `pc.configureIndex`, still work in `v9` but are deprecated in favor of resource clients such as `pc.indexes`. > [!WARNING] > > Before upgrading to `v9.0.0`, update all relevant code to account for the following breaking changes. See the [v9 migration guide](https://github.com/pinecone-io/pinecone-ts-client/blob/main/guides/upgrading/v9-migration.md) for before-and-after examples. > > * Node.js 22 or later is required. > * `pc.preview` and the `Preview*` exports are removed. Document operations move to `index.documents`, where `index` comes from `pc.index({ name, namespace })` or `pc.index(name).namespace(namespace)`. Control operations move to resource clients such as `pc.indexes`. > * Pod-based index creation, legacy metadata-indexing schemas, and the `sourceCollection` and `sourceBackupId` creation options are rejected. Existing pod-based indexes keep working. To restore from a backup, use `pc.backups.createIndex(backupId, options)`. > * A top-level `embed` option when configuring an index is rejected. Update the semantic field through a `schema.fields` patch instead. > * Legacy index response properties such as `dimension`, `metric`, and `spec` are compatibility getters derived from `schema` and `deployment`. They are omitted when a response is spread or serialized, and can throw `Errors.PineconeIndexPropertyError` when there is no legacy equivalent. > * `NamespaceDescription.recordCount` and `sizeBytes` are now decimal strings, and `BackupModel.createdAt` is now a `Date`. > * Some generated type names are renamed or removed. For example, `BackupPaginationResponse` is now `BackupListPagination`. 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](/admin/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](/admin/security/manage-rbac), initialize an `AdminClient` with [service account](/admin/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. > [!NOTE] > > 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. > [!TIP] > > 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`. The base install includes the sync and [async](#async-requests) clients and the [gRPC](https://grpc.io/) data-plane client, so there are no extras to install. ## Requirements The Pinecone Python SDK requires Python 3.10 or later. It has been tested with CPython versions from 3.10 to 3.14. ## 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 | | :- | :- | | `2026-07` | v10.x | | `2026-04` | v9.x | | `2025-10` | v8.x | | `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 ``` To install a specific version of the Python SDK, run the following command: ```shell pip theme={null} # Install a specific version pip install pinecone== ``` SDK versions 8.x and earlier shipped gRPC and asyncio support as optional extras. To use them on those versions, install `"pinecone[grpc]=="` or `"pinecone[asyncio]=="`. To check your SDK version, run the following command: ```shell pip theme={null} pip show pinecone ``` > [!NOTE] > > 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's 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 > [!WARNING] > > 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 ``` ## Initialize Once installed, you can import the library and then use an [API key](/admin/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/indexes/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's disabled when set to `False`. It's 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 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 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/indexes/index-data-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. > [tab] Python SDK without gRPC > > When using the Python SDK without gRPC, to get good performance, it's 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 aren't 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) > ``` > [tab] Python SDK with gRPC > > When using the Python SDK with gRPC, 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 with the [Python SDK](/reference/sdks/python/overview), use the `upsert_from_dataframe` method. It upserts in batches (set the size with `batch_size`), retries failed requests, and performs especially well with data loaded from Parquet files. The dataframe needs `id` and `values` columns, plus an optional `metadata` column. ```Python Python theme={null} import pandas as pd from pinecone import Pinecone pc = Pinecone(api_key="API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/target-an-index index = pc.Index(host="INDEX_HOST") # To load a Parquet file instead, use pd.read_parquet("path/to/file.parquet") df = pd.DataFrame({ "id": ["A", "B", "C"], "values": [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6], [0.7, 0.8, 0.9]], "metadata": [{"genre": "drama"}, {"genre": "comedy"}, {"genre": "drama"}], }) index.upsert_from_dataframe(df, namespace="example-namespace", batch_size=500) ``` # 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 > [tab] Databricks platform > > 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.2.0/spark-pinecone-uberjar.jar > ``` > > > [!NOTE] > > > > Databricks platform users must use the Pinecone assembly jar listed above to ensure that the proper dependecies are installed. > > 3. Click **Install**. > [tab] Databricks on AWS > > 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.2.0/spark-pinecone-uberjar.jar > ``` > > 3. Click **Install**. > [tab] Databricks on GCP / Azure > > 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.2.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() } ``` > [!TIP] > > 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) # Pinecone API 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](/admin/security/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; 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", "disabled", null); } } ``` ```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: 2026-07" \ -d '{ "name": "docs-example", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "_values": { "type": "dense_vector", "dimension": 1536, "metric": "cosine" } } } }' ``` ## Add headers to an HTTP request All HTTP requests to Pinecone APIs must contain an `Api-Key` header that specifies a valid [API key](/admin/security/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: 2026-07" \ -d '{ "name": "docs-example", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "_values": { "type": "dense_vector", "dimension": 1536, "metric": "cosine" } } } }' ``` ## Troubleshooting > [accordion] Initialization errors due to outdated SDKs > > 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 overview Source: https://docs.pinecone.io/reference/api/database-limits Reference for Pinecone Database rate, object, operation, and identifier limits, plus known index and serverless limitations. This page describes the limits and known limitations for Pinecone Database. Each topic has its own reference page: * **[Rate limits](/reference/api/database-limits/rate-limits)**: request-per-second, monthly usage, and model throughput limits that vary by pricing plan, plus the `429` errors you get when you exceed them. * **[Object limits](/reference/api/database-limits/object-limits)**: the number or size of projects, users, indexes, namespaces, storage, backups, and collections allowed by plan. * **[Operation limits](/reference/api/database-limits/operation-limits)**: fixed batch-size limits for upsert, import, query, fetch, and delete, plus metadata filter limits. * **[Identifier limits](/reference/api/database-limits/identifier-limits)**: maximum length and allowed characters for organization, project, index, namespace, and record identifiers. * **[Known limitations](/reference/api/known-limitations)**: index and serverless caveats, such as upsert consistency and metadata rules. > [!NOTE] > > If a limit is blocking you, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. Many limits can be raised on request, and Support can often suggest a workaround for the ones that can't. # Identifier limits Source: https://docs.pinecone.io/reference/api/database-limits/identifier-limits Maximum length and allowed characters for Pinecone identifiers, including organization, project, index, namespace, and record names. An identifier is a string of characters used to identify "named" [objects in Pinecone](/guides/get-started/key-terms). The following Pinecone objects use strings as identifiers: | Object | Field | Max # characters | Allowed characters | | - | - | - | - | | [Organization](/guides/get-started/key-terms#organization) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Project](/guides/get-started/key-terms#project) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Index](/guides/get-started/key-terms#index) | `name` | 45 |
  • `a-z`, `0-9`, and `-`
  • Must be lowercase
  • Cannot start or end with `-`
  • Cannot be empty
| | [Namespace](/guides/get-started/key-terms#namespace) | `namespace` | 512 |
  • ASCII except `\0`
  • For the default namespace, use `""` (or `"__default__"`, in API versions `2025-04` and later)
| | [Namespace alias](/guides/data/namespace-aliases/overview) | `name` | 512 |
  • ASCII graphic characters
  • No spaces or `/ ? # % & = \ ; +`
  • `.`, `..`, and `__default__` are reserved
  • Must be unique in the index and can't match a namespace name
| | [Record](/guides/get-started/key-terms#record) | `id` | 512 |
  • ASCII except `\0`
  • Cannot be empty
| # Object limits Source: https://docs.pinecone.io/reference/api/database-limits/object-limits Limits on the number and size of Pinecone Database projects, indexes, namespaces, storage, backups, and collections, by plan. Object limits are restrictions on the number or size of objects in Pinecone. They vary based on [pricing plan](https://www.pinecone.io/pricing/). | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | Projects per organization | 1 | 5 | 20 | 100 | | Users per organization | 2 | 5 | Unlimited | Unlimited | | Serverless indexes per project 1 | 5 | 10 | 20 | 200 | | Serverless index storage per org | 2 GB | 10 GB | N/A | N/A | | Namespaces per serverless index | 100 | 1,000 | 100,000 | 1,000,000 | | Namespace aliases per serverless index | 1,000 | 1,000 | 1,000 | 1,000 | | Serverless backups per project | N/A | N/A | 500 | 1,000 | | 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/indexes/index-configuration#cloud-regions).\ When you exceed an object limit, API operations return a `403 - QUOTA_EXCEEDED`. [Upgrade your plan](/admin/billing/upgrade-billing-plan) to increase the limit. If a higher plan still doesn't cover what you need, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case, since most object limits can be raised on request. > [accordion] Example error > > ``` > Request failed. You've reached the max projects allowed in organization . > To add more projects, upgrade your plan. > ``` For the serverless storage limit, you can also [delete records](/guides/data/delete-data) to get back under it. > [!TIP] > > To stay under the serverless index limit, use [namespaces](/guides/indexes/create-an-index#namespaces) to partition data within a single index instead of creating multiple indexes. This can also improve query performance and lower costs by limiting searches to relevant data subsets. > [!NOTE] > > [Namespaces per serverless index](/reference/api/database-limits/object-limits) vary by plan (100 on Starter to 1,000,000 on Enterprise). Pinecone can accommodate more for specific use cases. If your application needs a higher limit, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). # Operation limits Source: https://docs.pinecone.io/reference/api/database-limits/operation-limits Fixed limits on Pinecone Database operations, including upsert, update, import, query, fetch, and delete batch sizes and metadata filter expressions. Operation limits are restrictions on the size, number, or other characteristics of operations in Pinecone. Operation limits are fixed and don't vary based on pricing plan. If one of these limits is blocking you, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. There's often a workaround. ## Upsert limits | Metric | Limit | | :- | :- | | Max [batch size](/guides/legacy/vectors-api/upsert-vectors#upsert-in-batches) for records with vectors | 1,000 records, up to 2 MB total | | Max batch size for records with text | 96 records | | Max documents per upsert request | 1,000, or 96 when the schema declares `embed` or `sparse_embed` | | 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](/guides/search/full-text-search/text-processing#tokens-and-analyzers) | 1,024 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 limit for text is lower because Pinecone converts that text to vectors at upsert time with [integrated embedding](/guides/indexes/index-data-overview#integrated-embedding), and 96 is the max batch size of the [hosted embedding models](/guides/indexes/index-configuration#embedding-models) doing the conversion. The 40 KB filterable metadata limit doesn't apply to `full_text_search` text fields. ## Update limits | Metric | Limit | | :- | :- | | Max documents per by-ID document update request | 1,000, or 96 when the schema declares `embed` or `sparse_embed` | | Max records per update-by-metadata request | 100,000 | ## Import limits > [!NOTE] > > If your import exceeds these limits, you'll get an error specifying the limit exceeded. See [Troubleshooting](/guides/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 doesn't apply to indexes with [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview). Bulk import supports indexes without a schema definition (Parquet files) and indexes with document schemas ([JSONL files](/guides/data/import-data#prepare-document-schema-files-jsonl)). Semantic-text (auto-embedded) fields aren't 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. > [!TIP] > > 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/legacy/vectors-api/fetch-vectors#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 returns 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 multitenancy](/guides/data/design-for-multitenancy). * **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 multitenancy](/guides/data/design-for-multitenancy#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. > [!TIP] > > 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. # Rate limits Source: https://docs.pinecone.io/reference/api/database-limits/rate-limits Request-per-second, monthly usage, and model throughput limits for Pinecone Database serverless indexes, and the 429 errors returned when you exceed them. Rate limits help protect your applications from misuse and maintain the health of our shared serverless infrastructure. They vary by [pricing plan](https://www.pinecone.io/pricing/) and apply to [serverless indexes](/guides/indexes/index-data-overview) only. Request-per-second limits are enforced per namespace or per index, as noted in the [Data operation throughput limits](#data-operation-throughput-limits) table, in addition to your read and write unit limits, so a request fails if it exceeds any applicable limit. When you exceed a limit, the request returns a `429 - TOO_MANY_REQUESTS` and the error message names the limit, scope, and value. **Most rate limits can be adjusted upon request.** If you need higher limits, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. > [!NOTE] > > Indexes built on [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) aren't subject to read unit limits for query, fetch, list, and full-text search operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) guide. ## Monthly usage limits [Read units](/guides/cost/understand-cost#read-units) and [write units](/guides/cost/understand-cost#write-units) measure resource consumption. To check your current usage, see [Download a usage report](/admin/billing/download-usage-report). | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | Read units per month per org | 1,000,000 | 2,000,000 | Unlimited | Unlimited | | Write units per month per org | 2,000,000 | 5,000,000 | Unlimited | Unlimited | | Embedding tokens per month per model | 5,000,000 | 10,000,000 | Unlimited | Unlimited | | `gemini-embedding-2` embedding tokens per month | Not available | 10,000,000 | Unlimited | Unlimited | > [!NOTE] > > From November 4 through December 31, 2026, Starter orgs get 10,000,000 embedding tokens per month per model, and Builder orgs get 20,000,000. Allowances return to the values in the table on January 1, 2027. Monthly rerank request limits vary by model: | Reranking model | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | `cohere-rerank-4-fast` | Not available | Not available | Unlimited | Unlimited | | `bge-reranker-v2-m3` | 500 | 1,000 | Unlimited | Unlimited | | `pinecone-rerank-v0` | 500 | Not available | Unlimited | Unlimited | Reaching a monthly usage limit returns a `429 - TOO_MANY_REQUESTS`. [Upgrade your plan](/admin/billing/upgrade-billing-plan) to continue. > [accordion] Example error > > ``` > Request failed. You've reached your read unit limit for the current month. > To continue reading data, upgrade your plan. > ``` ## Data operation throughput limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | Upsert size per second per namespace | 50 MB | 50 MB | 50 MB | 50 MB | | Query read units per second per namespace | 2,000 | 2,000 | 2,000 | 2,000 | | Query read units per second per index | 2,000 | 2,000 | 2,000 | 2,000 | | Query requests per second per namespace | 100 | 100 | 100 | 100 | | Update records per second per namespace | 100 | 100 | 100 | 100 | | Update requests per second per namespace | 100 | 100 | 100 | 100 | | Update by metadata requests per second per namespace | 20 | 20 | 20 | 20 | | Update by metadata requests per second per index | 500 | 500 | 500 | 500 | | Upsert requests per second per namespace | 100 | 100 | 100 | 100 | | Fetch requests per second per index | 100 | 100 | 100 | 100 | | List requests per second per index | 200 | 200 | 200 | 200 | | Describe index stats requests per second per index | 100 | 100 | 100 | 100 | | Delete requests per second per namespace | 100 | 100 | 100 | 100 | | Delete records per second per namespace | 5,000 | 5,000 | 5,000 | 5,000 | | Delete records per second per index | 5,000 | 5,000 | 5,000 | 5,000 | | Delete by metadata requests per second per namespace | 20 | 20 | 20 | 20 | | Delete by metadata requests per second per index | 500 | 500 | 500 | 500 | The per-namespace and per-index query read unit limits are enforced separately. At the defaults they're equal, so the namespace limit only matters once the index limit is raised. When you ask Support for a higher read limit, ask for both, or each namespace stays capped at its current limit. Exceeding a per-second throughput limit returns a `429 - TOO_MANY_REQUESTS`. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic), pace your requests, consider [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) (which aren't subject to per-second read limits) for high-throughput reads, or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) to raise a limit. > [accordion] Example 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. > ``` ## Model throughput limits Per-minute token limits for embedding models: | 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 | | `gemini-embedding-2` | Passage | Not available | 250,000 | 2,000,000 | 2,000,000 | | | Query | Not available | 50,000 | 250,000 | 250,000 | | `text-embedding-3-small` | Passage | 250,000 | 250,000 | 2,000,000 | 2,000,000 | | | Query | 50,000 | 50,000 | 250,000 | 250,000 | | `text-embedding-3-large` | Passage | 250,000 | 250,000 | 2,000,000 | 2,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 | Per-minute request limits for reranking models: | Reranking model | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | `cohere-rerank-4-fast` | Not available | Not available | 300 | 300 | | `bge-reranker-v2-m3` | 60 | 60 | 60 | 60 | | `pinecone-rerank-v0` | 60 | Not available | 60 | 60 | Reaching a per-minute model limit returns a `429 - TOO_MANY_REQUESTS`. [Upgrade your plan](/admin/billing/upgrade-billing-plan) to increase it, or [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). > [accordion] Example 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. > ``` ## Inference request limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | Inference requests per second per project | 100 | 100 | 100 | 100 | | Inference requests per minute per project | 2,000 | 2,000 | 2,000 | 2,000 | These limits apply per project across all models. Every inference request counts toward them, including requests that a [per-minute token limit](#model-throughput-limits) then rejects. Exceeding the per-second or per-minute limit returns a `429 - TOO_MANY_REQUESTS`. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle it. > [accordion] Example error > > ``` > Request failed. You've reached the max inference requests per second () for the current project. > ``` > > The message names the per-second or per-minute limit, whichever you exceeded. # Pinecone API errors Source: https://docs.pinecone.io/reference/api/errors Look up the HTTP status codes the Pinecone API returns, plus the causes and fixes for common Pinecone API and SDK error messages. Look up an [HTTP status code](#http-status-codes), or find an exact error message under [Index creation errors](#index-creation-errors) or [Outdated Python SDK errors](#outdated-python-sdk-errors). For handling errors in production, see [Error handling](/guides/production/error-handling). ## HTTP status codes 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. ### 200 - OK The request succeeded. ### 201 - CREATED The request succeeded and a new resource was created. ### 202 - ACCEPTED The request was accepted, but the operation isn't complete yet. For example, deleting an index returns `202` while the deletion is still in progress. ### 204 - NO CONTENT The request succeeded, and there's no response body 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](/admin/projects/projects-overview#api-keys). ### 402 - PAYMENT REQUIRED The request failed due to delinquent payment or account deactivation for non-payment. See [Account deactivation for non-payment](/admin/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/indexes/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. ## Index creation errors ### Missing spec argument ```console theme={null} TypeError: Pinecone.create_index() missing 1 required positional argument: 'spec' ``` Python SDK versions 3.0.0 to 9.x require a `spec` argument in `create_index()`. Pass one to set the index's cloud and region: ```python Python theme={null} from pinecone import Pinecone, 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"), ) ``` In Python SDK 10, `spec` is optional and new indexes default to AWS `us-east-1`. For current syntax, see [Create an index](/guides/indexes/create-an-index). ### Serverless index limit reached ```console theme={null} Request failed. You've reached the max serverless indexes allowed in project PROJECT_NAME (LIMIT). Use namespaces to partition your data into logical groups, or upgrade your plan to add more serverless indexes. ``` The API returns this with status `403` when the project already has as many serverless indexes as your plan allows. For the limit on each plan, see [Object limits](/reference/api/database-limits/object-limits). To fix it, do one of the following: * [Delete indexes](/guides/indexes/manage-indexes#delete-an-index) you no longer need. * Store data in [namespaces](/guides/data/implement-multitenancy) within one index instead of creating separate indexes. * [Upgrade your plan](/admin/billing/upgrade-billing-plan). ## Outdated Python SDK errors These errors come from code written for Python SDK versions earlier than 3.0.0, or from having the deprecated `pinecone-client` package installed. ### Pinecone has no attribute init ```console theme={null} AttributeError: module 'pinecone' has no attribute 'init' ``` In Python SDK 5.0.0 and later, the message reads: ```console theme={null} AttributeError: init is no longer a top-level attribute of the pinecone package. Please create an instance of the Pinecone class instead. ``` The code calls `pinecone.init()`, which was removed in version 3.0.0. Create a client instance instead. It doesn't take an environment, only an API key: ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` The same applies to other former top-level functions, such as `pinecone.create_index()` and `pinecone.list_indexes()`. Call them on the client instance instead. ### Cannot import name Pinecone ```console theme={null} ImportError: cannot import name 'Pinecone' from 'pinecone' ``` The installed SDK is earlier than 3.0.0, or the deprecated `pinecone-client` package is installed alongside `pinecone`. The Python SDK package was renamed from `pinecone-client` to `pinecone`, and having both installed causes conflicts. Remove the old package and upgrade: ```shell Shell theme={null} pip uninstall pinecone-client pip install --upgrade pinecone ``` ### Controller hostname not found ```console theme={null} Failed to resolve 'controller.us-west-2.pinecone.io' controller.us-west-2-aws.pinecone.io not found Request failed to reach Pinecone while calling https://controller.us-west-2.pinecone.io/actions/whoami ``` SDK versions earlier than 3.0.0 send requests to environment-specific `controller` hostnames. Current SDKs use `https://api.pinecone.io`. Upgrade the SDK, then update your code as described in [Pinecone has no attribute init](#pinecone-has-no-attribute-init): ```shell Shell theme={null} pip install --upgrade pinecone ``` # 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. > [!NOTE] > > [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: > [card] [CLI](/reference/cli/overview) > [card] [Python SDK](/reference/sdks/python/overview) > [card] [Node.js SDK](/reference/sdks/node/overview) > [card] [Java SDK](/reference/sdks/java/overview) > [card] [Go SDK](/reference/sdks/go/overview) ## Inference Use the Inference API to generate vector embeddings and rerank results using [embedding models](/guides/indexes/index-configuration#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-results) and [Generate vectors](/reference/api/latest/inference/generate-vectors) 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: > [card] [Python SDK](/reference/sdks/python/overview) > [card] [Node.js SDK](/reference/sdks/node/overview) > [card] [Java SDK](/reference/sdks/java/overview) > [card] [Go SDK](/reference/sdks/go/overview) # 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. ## Upserts * Pinecone is eventually consistent, so there can be a slight delay before [upserted records](/guides/data/upsert-data) are available to query. After upserting records, use the [Get index stats](/reference/api/latest/data-plane/describeindexstats) operation to check whether 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/indexes/index-data-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 don't support sparse vectors. ## Metadata * Null metadata values aren't supported. Instead of setting a key to `null`, remove the key from the metadata payload. * Nested JSON objects aren't supported. ## Serverless indexes Serverless indexes don't support the following features: * [Filtering index statistics by metadata](/reference/api/latest/data-plane/describeindexstats) * [Private endpoints](/guides/production/configure-private-endpoints) * This feature is available on AWS only. # Pinecone API versioning Source: https://docs.pinecone.io/reference/api/versioning Learn how Pinecone versions its APIs by release date, how long each stable version is supported, and how to set the X-Pinecone-Api-Version header. 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: ![](https://mintcdn.com/pinecone/9qvQp5nU6duJvusQ/images/api-versioning.png?fit=max\&auto=format\&n=9qvQp5nU6duJvusQ\&q=85\&s=be4366853edee83e003c3863e31fa1ce) ## Specify an API version > [!WARNING] > > 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-07`) 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-07" ``` 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 [changelog](/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](/admin/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](/admin/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" ``` > [!WARNING] > > 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 > [!NOTE] > > 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" ``` > [!NOTE] > > 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). > [!NOTE] > > `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 > [accordion] pc login (Authenticate via user login) > > **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" > ``` > > > [!NOTE] > > > > This is an alias for `pc auth login`. Both commands perform the same operation. > [accordion] pc logout (Clear credentials / log out) > > **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 > ``` > > > [!NOTE] > > > > 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. > [accordion] pc target (Set target organization and project) > > **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 > ``` > [accordion] pc version (Show CLI version) > > **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 > ``` > [accordion] pc whoami (Show current user) > > **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 > ``` > > > [!NOTE] > > > > This is an alias for `pc auth whoami`. Both commands perform the same operation. ### Authentication > [accordion] pc auth clear (Clear specific credentials) > > **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 > ``` > > > [!NOTE] > > > > 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`. > [accordion] pc auth configure (Configure service account or API key) > > **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 > ``` > > > [!NOTE] > > > > `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). > [accordion] pc auth local-keys list (List managed keys) > > **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 > ``` > [accordion] pc auth local-keys prune (Delete managed keys) > > **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 > ``` > > > [!NOTE] > > > > This deletes keys from both local storage and Pinecone servers. Use `--dry-run` to preview before committing. > [accordion] pc auth login (Authenticate via user login) > > **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 > ``` > > > [!NOTE] > > > > 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`. > [accordion] pc auth logout (Clear authentication credentials) > > **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 > ``` > > > [!NOTE] > > > > 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. > [accordion] pc auth status (Show authentication status) > > **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 > ``` > [accordion] pc auth whoami (Show current user information) > > **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 > ``` > > > [!NOTE] > > > > This command does the same thing as `pc whoami`. ### Indexes > [accordion] pc index configure (Update index configuration) > > **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 > ``` > > > [!NOTE] > > > > Configuration changes may take some time to take effect. > [accordion] pc index create (Create a new index) > > **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 > ``` > > > [!NOTE] > > > > For a list of valid regions for a serverless index, see [Create a serverless index](/guides/indexes/create-an-index). > [accordion] pc index delete (Delete 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 > ``` > > > [!NOTE] > > > > This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. > [accordion] pc index describe (Show index details) > > **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 > ``` > [accordion] pc index stats (Show index statistics) > > **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 > ``` > [accordion] pc index list (List all indexes) > > **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 > [accordion] pc index namespace create (Create a namespace) > > **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 > ``` > [accordion] pc index namespace delete (Delete a namespace) > > **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 > ``` > > > [!WARNING] > > > > Deleting a namespace removes all vectors in that namespace. This operation cannot be undone. > [accordion] pc index namespace describe (Show namespace details) > > **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 > ``` > [accordion] pc index namespace list (List namespaces) > > **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 > [accordion] pc index vector delete (Delete 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 > ``` > > > [!NOTE] > > > > 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. > > > [!WARNING] > > > > Vector deletion is permanent and cannot be undone. > [accordion] pc index vector fetch (Fetch vectors by ID or filter) > > **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 > ``` > > > [!NOTE] > > > > Use either `--ids` or `--filter`, not both. When using `--ids`, pagination flags are not applicable. > [accordion] pc index vector list (List vector IDs) > > **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 > ``` > [accordion] pc index vector query (Query vectors) > > **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 > ``` > > > [!NOTE] > > > > Use `--id`, `--vector`, or sparse vectors (`--sparse-indices` and `--sparse-values`) to specify what to query against. These options are mutually exclusive. > [accordion] pc index vector update (Update vectors) > > **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"}' > ``` > > > [!NOTE] > > > > Use either `--id` for single vector updates or `--filter` for bulk updates. These options are mutually exclusive. > [accordion] pc index vector upsert (Upsert vectors) > > **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 > ``` > > > [!NOTE] > > > > **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 > [accordion] pc index record search (Search records in an index) > > **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..."} > ``` > [accordion] pc index record upsert (Upsert records into an integrated index) > > **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 > [accordion] pc index collection create (Create a collection from a pod-based index) > > **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 > ``` > [accordion] pc index collection delete (Delete a collection) > > **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 > ``` > > > [!NOTE] > > > > This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. > [accordion] pc index collection describe (Describe a collection by name) > > **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 > ``` > [accordion] pc index collection list (List collections in your project) > > **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 > [accordion] pc index backup create (Create a backup) > > **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 > ``` > [accordion] pc index backup delete (Delete a backup) > > **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 > ``` > > > [!NOTE] > > > > This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. > > > [!WARNING] > > > > Backup deletion is permanent and cannot be undone. > [accordion] pc index backup describe (Show backup details) > > **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 > ``` > [accordion] pc index backup list (List backups) > > **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 > ``` > [accordion] pc index restore (Restore an index from a backup) > > **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 > ``` > [accordion] pc index restore describe (Show restore job details) > > **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 > ``` > [accordion] pc index restore list (List restore jobs) > > **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 > [accordion] pc index import start (Start an import from a storage URI) > > **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 > ``` > [accordion] pc index import describe (Describe an import operation) > > **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 > ``` > [accordion] pc index import list (List import operations for an index) > > **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 - > ``` > [accordion] pc index import cancel (Cancel an in-progress import operation) > > **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 > [accordion] pc project create (Create a new project) > > **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" > ``` > [accordion] pc project delete (Delete a 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 > ``` > > > [!NOTE] > > > > 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. > [accordion] pc project describe (Show project details) > > **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 > ``` > [accordion] pc project list (List all projects) > > **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 > ``` > [accordion] pc project update (Update project settings) > > **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 > [accordion] pc organization delete (Delete an organization) > > **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 > ``` > > > [!NOTE] > > > > 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. > [accordion] pc organization describe (Show organization details) > > **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 > ``` > [accordion] pc organization list (List organizations) > > **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 > ``` > [accordion] pc organization update (Update organization settings) > > **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 > [accordion] pc api-key create (Create a new API key) > > **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 > ``` > > > [!NOTE] > > > > API keys are scoped to a specific organization and project. > [accordion] pc api-key delete (Delete an API key) > > **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 > ``` > > > [!NOTE] > > > > Deletion is permanent. Applications using this key immediately lose access to Pinecone. > [accordion] pc api-key describe (Show API key details) > > **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 > ``` > > > [!NOTE] > > > > Does not display the actual key value. > [accordion] pc api-key list (List all API keys) > > **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 > ``` > > > [!NOTE] > > > > Does not display key values. > [accordion] pc api-key update (Update API key settings) > > **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 > ``` > > > [!NOTE] > > > > Cannot change the actual key. If you need a different key, create a new one. ### Config > [accordion] pc config list (List all configuration settings and their current values) > > **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 > ``` > [accordion] pc config get \ (Get the current value of a configuration setting) > > **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 > ``` > [accordion] pc config describe \ (Show detailed information about a configuration setting) > > **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 > ``` > [accordion] pc config set \ \ (Set a configuration value) > > **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 > ``` > [accordion] pc config unset \ (Reset a configuration value to its default) > > **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 > [tab] macOS (Homebrew) > > ```bash theme={null} > brew tap pinecone-io/tap > brew install pinecone-io/tap/pinecone > ``` > [tab] Other platforms > > 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" ``` > [!TIP] > > 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 Set the Pinecone CLI target context with pc target to control which organization and project your commands run against, including in CI/CD and JSON mode. 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. | > [!NOTE] > > `--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 > [!WARNING] > > 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 can't 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 don't 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). > [card] [Python SDK](/reference/sdks/python/overview) > [card] [Node.js SDK](/reference/sdks/node/overview) > [card] [Java SDK](/reference/sdks/java/overview) > [card] [Go SDK](/reference/sdks/go/overview) ## 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-07` | `2026-04` | `2025-10` | `2025-04` | `2025-01` | `2024-10` | `2024-07` | `2024-04` | | - | :- | :- | :- | :- | :- | :- | :- | :- | | [Python SDK](/reference/sdks/python/overview) | v10.x | 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) | v9.x | v8.x | v7.x | v6.x | v5.x | v4.x | v3.x | v2.x | | [Java SDK](/reference/sdks/java/overview) | Coming soon | Coming soon | v6.x | v5.x | v4.x | v3.x | v2.x | v1.x | | [Go SDK](/reference/sdks/go/overview) | v7.x | 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. > [!NOTE] > > 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 search, query, fetch, and list responses. For example, if a search 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/monitor-performance) or the organization-wide [Usage dashboard](/admin/billing/download-usage-report). ## Community SDKs Find community-contributed SDKs for Pinecone. These libraries aren't 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. > [!TIP] > > 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-07` | v7.x | | `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/v7/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/v7/pinecone@ ``` To check your SDK version, run the following command: ```shell theme={null} go list -u -m all | grep go-pinecone ``` ## Upgrade > [!WARNING] > > Before upgrading to `v7.0.0`, update all relevant code to account for the following breaking changes. See the [v7 migration guide](https://github.com/pinecone-io/go-pinecone/blob/main/guides/migration/v7.md) for before-and-after examples. > > * Pod-based index creation is removed. `CreatePodIndex` and `CreatePodIndexRequest` no longer exist, but existing pod-based indexes keep working. > * Enum constants are prefixed with their type name. For example, `Aws` is now `CloudAWS`, and `Cosine` is now `IndexMetricCosine`. > * `ListImports` takes a `*ListImportsRequest`, and `QueryByVectorIdRequest.SparseValues` is removed. > * `SourceCollection` and `Schema` on the legacy create requests now return an error. `ConfigureIndexParams.Embed` is replaced by `ConfigureIndexParams.Schema`. > * `Backup` field types changed, and some invalid requests now fail client-side. > > If you are upgrading from `v2` or earlier, also account for the `v3.0.0` 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 `v6` to `v7` means changing: ```go theme={null} // before import "github.com/pinecone-io/go-pinecone/v6/pinecone" // after import "github.com/pinecone-io/go-pinecone/v7/pinecone" ``` Apart from the module path, `v5.0.0` and `v6.0.0` are backward compatible with the release lines before them. `v7.0.0` targets API version `2026-07` and includes the breaking changes listed above. To stay on API version `2026-04`, keep using `v6`. 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/v7/pinecone@latest ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/admin/security/security-overview#api-keys) to initialize a client instance: ```Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v7/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](/admin/security/manage-rbac), initialize an `AdminClient` with [service account](/admin/organizations/manage-service-accounts) credentials instead: ```Go theme={null} package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v7/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) ``` > [!NOTE] > > 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)); ``` > [!TIP] > > 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) aren't currently instrumented. * **Bulk import operations** aren't yet instrumented. * **Server duration may be unavailable.** The `getServerDurationMs()` method returns `null` if the `x-pinecone-response-duration-ms` header isn't 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 don't 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 raised 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. > [!TIP] > > 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-10` | v6.x | | `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 6.3.0 # Gradle implementation "io.pinecone:pinecone-client:6.3.0" ``` Alternatively, you can download the standalone uberjar [pinecone-client-6.3.0-all.jar](https://repo1.maven.org/maven2/io/pinecone/pinecone-client/6.3.0/pinecone-client-6.3.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 > [!WARNING] > > Before upgrading from `v5.x` to `v6.x`, update code that passes enum values. Deletion protection, cloud, and import error mode now take strings, such as `"enabled"`, `"aws"`, and `"continue"`. For the full list of breaking changes, see the [`v6.0.0` release notes](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v6.0.0). 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 6.3.0 # Gradle implementation "io.pinecone:pinecone-client:6.3.0" ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/admin/security/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. > [!TIP] > > 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.js SDK requires Node.js 22 or later. Its type declarations support TypeScript 5.2 to 7.x. The SDK is for server-side use only. Running it in a browser exposes your API key, so call Pinecone from your backend instead. ## 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-07` | v9.x | | `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 `v9.0.0` targets API version `2026-07`. To stay on API version `2026-04`, keep using `v8`. The flat control methods, such as `pc.createIndex` and `pc.configureIndex`, still work in `v9` but are deprecated in favor of resource clients such as `pc.indexes`. > [!WARNING] > > Before upgrading to `v9.0.0`, update all relevant code to account for the following breaking changes. See the [v9 migration guide](https://github.com/pinecone-io/pinecone-ts-client/blob/main/guides/upgrading/v9-migration.md) for before-and-after examples. > > * Node.js 22 or later is required. > * `pc.preview` and the `Preview*` exports are removed. Document operations move to `index.documents`, where `index` comes from `pc.index({ name, namespace })` or `pc.index(name).namespace(namespace)`. Control operations move to resource clients such as `pc.indexes`. > * Pod-based index creation, legacy metadata-indexing schemas, and the `sourceCollection` and `sourceBackupId` creation options are rejected. Existing pod-based indexes keep working. To restore from a backup, use `pc.backups.createIndex(backupId, options)`. > * A top-level `embed` option when configuring an index is rejected. Update the semantic field through a `schema.fields` patch instead. > * Legacy index response properties such as `dimension`, `metric`, and `spec` are compatibility getters derived from `schema` and `deployment`. They are omitted when a response is spread or serialized, and can throw `Errors.PineconeIndexPropertyError` when there is no legacy equivalent. > * `NamespaceDescription.recordCount` and `sizeBytes` are now decimal strings, and `BackupModel.createdAt` is now a `Date`. > * Some generated type names are renamed or removed. For example, `BackupPaginationResponse` is now `BackupListPagination`. 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](/admin/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](/admin/security/manage-rbac), initialize an `AdminClient` with [service account](/admin/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. > [!NOTE] > > 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. > [!TIP] > > 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`. The base install includes the sync and [async](#async-requests) clients and the [gRPC](https://grpc.io/) data-plane client, so there are no extras to install. ## Requirements The Pinecone Python SDK requires Python 3.10 or later. It has been tested with CPython versions from 3.10 to 3.14. ## 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 | | :- | :- | | `2026-07` | v10.x | | `2026-04` | v9.x | | `2025-10` | v8.x | | `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 ``` To install a specific version of the Python SDK, run the following command: ```shell pip theme={null} # Install a specific version pip install pinecone== ``` SDK versions 8.x and earlier shipped gRPC and asyncio support as optional extras. To use them on those versions, install `"pinecone[grpc]=="` or `"pinecone[asyncio]=="`. To check your SDK version, run the following command: ```shell pip theme={null} pip show pinecone ``` > [!NOTE] > > 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's 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 > [!WARNING] > > 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 ``` ## Initialize Once installed, you can import the library and then use an [API key](/admin/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/indexes/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's disabled when set to `False`. It's 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 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 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/indexes/index-data-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. > [tab] Python SDK without gRPC > > When using the Python SDK without gRPC, to get good performance, it's 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 aren't 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) > ``` > [tab] Python SDK with gRPC > > When using the Python SDK with gRPC, 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 with the [Python SDK](/reference/sdks/python/overview), use the `upsert_from_dataframe` method. It upserts in batches (set the size with `batch_size`), retries failed requests, and performs especially well with data loaded from Parquet files. The dataframe needs `id` and `values` columns, plus an optional `metadata` column. ```Python Python theme={null} import pandas as pd from pinecone import Pinecone pc = Pinecone(api_key="API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/target-an-index index = pc.Index(host="INDEX_HOST") # To load a Parquet file instead, use pd.read_parquet("path/to/file.parquet") df = pd.DataFrame({ "id": ["A", "B", "C"], "values": [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6], [0.7, 0.8, 0.9]], "metadata": [{"genre": "drama"}, {"genre": "comedy"}, {"genre": "drama"}], }) index.upsert_from_dataframe(df, namespace="example-namespace", batch_size=500) ``` # 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 > [tab] Databricks platform > > 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.2.0/spark-pinecone-uberjar.jar > ``` > > > [!NOTE] > > > > Databricks platform users must use the Pinecone assembly jar listed above to ensure that the proper dependecies are installed. > > 3. Click **Install**. > [tab] Databricks on AWS > > 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.2.0/spark-pinecone-uberjar.jar > ``` > > 3. Click **Install**. > [tab] Databricks on GCP / Azure > > 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.2.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() } ``` > [!TIP] > > 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 ## [Full-text search](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/full-text-search.ipynb) Search typed JSON documents using BM25 scoring, Lucene query syntax, dense vector ranking of images. Full-text search BM25 gemini-embedding-2 ## [Semantic search](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/semantic-search.ipynb) Implement semantic search over an index with dense vectors to find records that are similar in meaning to a given query. Integrated embedding ![](/images/examples/huggingface-icon.svg) Hugging Face Datasets llama-text-embed-v2 ## [Lexical search](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/lexical-search.ipynb) Implement lexical search over an index of sparse vectors to find records that most exactly match the words or phrases in a query. Integrated embedding Integrated reranking pinecone-sparse-english-v0 bge-reranker-v2-m3 ## [Cascading retrieval](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/cascading-retrieval.ipynb) Implement cascading retrieval (hybrid search with two indexes) to combine the benefits of semantic and lexical search. Integrated embedding Standalone reranking llama-text-embed-v2 pinecone-sparse-english-v0 bge-reranker-v2-m3 ## [Reranking search results](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/pinecone-reranker.ipynb) Use Pinecone's reranking feature to enhance the accuracy of search results. Standalone reranking ![](https://cdn.sanity.io/images/vr8gru94/production/40b1d05ee1325e6d9e4886af4e76ff06d844faff-188x188.jpg) bge-reranker-v2-m3 ## Retrieval-augmented generation (RAG) ## [RAG with hybrid search and Claude](https://colab.research.google.com/github/pinecone-io/examples/blob/master/learn/generation/traditional-rag/traditional-rag-with-claude-and-hybrid.ipynb) Implement simple retrieval-augmented generation with hybrid search and Anthropic's Claude models claude-3-5-haiku-latest llama-text-embed-v2 pinecone-sparse-english-v0 Dense Indexes Sparse Indexes Hybrid Search ## [Agentic RAG with Claude](https://colab.research.google.com/github/pinecone-io/examples/blob/master/learn/generation/agentic-rag/agentic-rag-with-claude.ipynb) Build an agentic RAG pipeline that uses tools to retrieve data from web search and Pinecone semantic search, then generates responses using Anthropic's Claude models claude-3-5-haiku-latest llama-text-embed-v2 Dense Indexes Tool use ## [RAG with LangChain and OpenAI](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/langchain-retrieval-augmentation.ipynb) Learn how RAG can be used with Pinecone to reduce hallucinations, by grounding responses using our own release notes ![](/images/examples/openai-icon.svg) gpt-5 ![](/images/examples/openai-icon.svg) text-embedding-3-small OpenAI LangChain ## [RAG with LlamaIndex and OpenAI](https://colab.research.google.com/github/pinecone-io/examples/blob/main/learn/generation/llama-index/using-llamaindex-with-pinecone.ipynb) Load a research paper with LlamaIndex, search it in Pinecone, and evaluate the relevance of the LLM's answers ![](/images/examples/openai-icon.svg) gpt-4o-mini ![](/images/examples/openai-icon.svg) text-embedding-3-small OpenAI LlamaIndex ## [RAG with cascading retrieval and OpenAI](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/gen-qa-openai.ipynb) Investigate research papers by implementing cascading retrieval, then pass results to OpenAI to generate answers ![](/images/examples/openai-icon.svg) gpt-4o-mini llama-text-embed-v2 pinecone-sparse-english-v0 Dense Indexes Sparse Indexes Cascading Retrieval ## [Retrieval agent with LangChain and OpenAI](https://colab.research.google.com/github/pinecone-io/examples/blob/main/learn/generation/langchain/handbook/08-langchain-retrieval-agent.ipynb) Build a conversational agent with memory that decides when to search a Pinecone index for context ![](/images/examples/openai-icon.svg) gpt-4o-mini ![](/images/examples/openai-icon.svg) text-embedding-3-small OpenAI LangChain ![](/images/examples/huggingface-icon.svg) Hugging Face Datasets ## [Retrieval Agents with Pinecone Assistant, LangChain and LangGraph](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/langchain-retrieval-agent.ipynb) Create a study guide generator using agentic retrieval and the Pinecone Assistant Context API ![](/images/examples/openai-icon.svg) gpt-4o-mini ![](/images/examples/openai-icon.svg) gpt-4.1 LangChain LangGraph Agentic Retrieval Structured Generation ## Miscellaneous ## [Import from object storage](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/pinecone-import.ipynb) Import documents from JSONL files in an Amazon S3 bucket into a document index Amazon S3 # 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. > [card] AWS Reference Architecture > > 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 Sample apps and tools built with Pinecone, including semantic search, multi-tenant RAG, multimodal search, Assistant chat, and pgvector migration. ## [Semantic search](/examples/sample-apps/legal-semantic-search) The Legal Semantic Search app shows you how to perform semantic search over PDF documents. ![](/images/examples/nextjs.svg) NextJS ![](/images/examples/openai-icon.svg) OpenAI ## [Multi-tenant RAG](/examples/sample-apps/namespace-notes) Namespace Notes is a simple multi-tenant RAG app. Upload documents that feed workspaces with context isolated by namespace. ![](/images/examples/nextjs.svg) NextJS ![](/images/examples/openai-icon.svg) OpenAI ## [Multimodal search](/examples/sample-apps/shop-the-look) The Shop the Look app shows you how to build multimodal search across text, images, and videos. ![](/images/examples/nextjs.svg) NextJS ![](/images/google-cloud-vertex-ai.svg) Google Vertex AI ## [Pinecone Assistant](/examples/sample-apps/pinecone-assistant) The Pinecone Assistant app connects a chat interface to your Pinecone Assistant to answer complex questions on your data. ![](/images/examples/nextjs.svg) NextJS ## [pgvector migration tool](https://github.com/pinecone-field/pgvector-migration) Migrate a vector-search workload from pgvector to Pinecone, validate the results, and synchronize changes until cutover. Python pgvector ## More code examples ## [Combine full-text search with dense vector ranking](https://github.com/pinecone-io/bird-search-example) A Python app to search typed JSON bird documents using BM25, Lucene query syntax, and dense vector ranking, powered by Gemini Embedding 2. ## [Rerank search results with natural language criteria](https://github.com/pinecone-io/using-typesafe-and-pinecone) A TypeScript app that retrieves bird articles with Pinecone full-text search, then reranks them with TypeSafe's Jev model. ## [Use the Python SDK with FastAPI](https://github.com/pinecone-io/fastapi-pinecone-async-example) A FastAPI app to demonstrate how to use the Pinecone Python SDK with asyncio support. ## [Implement semantic search with TypeScript](https://github.com/pinecone-io/semantic-search-example) A simple semantic search app written in TypeScript. ## [Build an article recommender with TypeScript](https://github.com/pinecone-io/recommender-example-typescript) A simple article recommender app written in TypeScript. ## [Create a chatbot agent with LangChain](https://github.com/pinecone-io/langchain-retrieval-agent-example) A conversational agent built with LangChain and TypeScript. ## [Implement image search with TypeScript](https://github.com/pinecone-io/image-search-example) An image search app written in TypeScript. # 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. Agent Skills work with [GitHub Copilot](https://github.com/features/copilot) and other agentic IDEs. [View on GitHub](https://github.com/pinecone-io/skills) > [!TIP] > > These tools have a dedicated Pinecone plugin with additional features. Install it instead of Agent Skills: > > * [Claude Code](/integrations/claude-code) > * [Codex](/integrations/codex) > * [Cursor](/integrations/cursor) ## Features * Built-in skills cover index management, semantic search, full-text search, assistant creation, and more. * The skills work in any IDE that supports Agent Skills. * The skills work 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/agents/mcp-server) configured in your IDE (optional, enables the `pinecone-query` skill) * [uv](https://docs.astral.sh/uv/getting-started/installation/) installed (required to run the bundled Python scripts, including the quickstart skill) * [Pinecone CLI](/reference/cli/quickstart) installed (optional, enables the `pinecone-cli` skill) ## Installation Set your API key, add the skills to your project, and optionally connect the MCP server. **1. Set your API key** ```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). **2. Install the skills** ```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. **3. Configure the MCP server (optional)** For full functionality, configure the [Pinecone MCP server](/guides/agents/mcp-server) in your IDE. This enables the `pinecone-query` skill and direct index operations. ## Available skills | Skill | Description | | - | - | | `pinecone-quickstart` | Step-by-step onboarding that walks you through creating an index, uploading data, and running your first search. | | `pinecone-query` | Search integrated indexes using natural language text via the Pinecone MCP. | | `pinecone-assistant` | Create, manage, and chat with Pinecone Assistants for document Q\&A with citations. | | `pinecone-cli` | Use the Pinecone CLI for terminal-based index and vector management across all index types. | | `pinecone-full-text-search` | Create, ingest into, and query a Pinecone full-text-search (FTS) index. | | `pinecone-n8n` | Build [n8n](/integrations/n8n) workflows with the Pinecone Assistant node or Pinecone Vector Store, including best practices and full workflow JSON generation. | | `pinecone-mcp` | Reference for all available Pinecone MCP server tools and their parameters. | | `pinecone-docs` | Curated links to official Pinecone documentation, organized by topic. | | `pinecone-help` | Overview of all skills and what you need to get started. | ## MCP tools Agent Skills work alongside the [Pinecone MCP server](/guides/agents/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 `pinecone-query` skill and direct index operations. For the full list of MCP tools, see [Use the Pinecone MCP server](/guides/agents/mcp-server). ## Resources * [GitHub repository](https://github.com/pinecone-io/skills) * [Pinecone MCP server guide](/guides/agents/mcp-server) # AI coding tools Source: https://docs.pinecone.io/integrations/ai-coding-tools Use Pinecone with AI coding tools like Claude Code, Codex, and Cursor through the Pinecone MCP server, plugins, and agent skills. Pinecone provides official plugins and agent skills for AI coding tools. Use the Pinecone [MCP server](/guides/agents/mcp-server) (Model Context Protocol) and built-in skills to manage 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 > [card] [Claude Code plugin](/integrations/claude-code) > > Official Pinecone plugin for Claude Code with skills, MCP tools, and slash commands. > [card] [Codex plugin](/integrations/codex) > > Official Pinecone plugin for Codex with skills and MCP tools. > [card] [Cursor plugin](/integrations/cursor) > > Official Pinecone plugin for Cursor with skills, MCP tools, and slash commands. > [card] [Agent Skills](/integrations/agent-skills) > > Universal skills library for GitHub Copilot and other agentic IDEs. > [card] [MCP server](/guides/agents/mcp-server) > > Connect any MCP-compatible client to Pinecone for index management and search. > [card] [Pinecone CLI](/reference/cli/quickstart) > > Direct terminal access to Pinecone. Manage indexes, namespaces, and records with `pc` commands. ## Tool recommendations | Your tool | What to install | Command | | - | - | - | | [Claude Code](https://claude.ai/code) | [Pinecone plugin for Claude Code](/integrations/claude-code) | `claude plugin install pinecone` | | [Codex](https://developers.openai.com/codex) | [Pinecone plugin for Codex](/integrations/codex) | See [install steps](/integrations/codex#installation) | | [Cursor](https://www.cursor.com/) | [Pinecone Cursor plugin](/integrations/cursor) | `/add-plugin pinecone` | | [GitHub Copilot](https://github.com/features/copilot) 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/agents/mcp-server) | See [MCP server setup](/guides/agents/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. Invocation names vary by tool, for example `/pinecone:quickstart` in Claude Code and `pinecone-quickstart` in Agent Skills. | Skill | Description | | - | - | | Quickstart | Step-by-step onboarding that walks you through creating an index, uploading data, and running 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. | | 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. | | 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/agents/mcp-server) provides tools for listing indexes, creating indexes, upserting records, searching, reranking, and more. # AI Engine Source: https://docs.pinecone.io/integrations/ai-engine Use the AI Engine WordPress plugin with Pinecone to power chatbots, semantic search, and RAG over site content directly from your WordPress dashboard. AI Engine is a WordPress plugin that connects WordPress with AI models. You can use it to create chatbots, generate content, build AI forms, and automate tasks from your WordPress dashboard. With Pinecone, AI Engine can power chatbots, semantic search, and retrieval-augmented generation (RAG) over your site content. With AI Engine, you can create a chatbot to assist your visitors, answer support questions, or guide users through your products and services. AI Engine can also write posts in your voice, rewrite existing ones, translate them into other languages, generate custom images for your articles, and refine text. For developers, AI Engine offers internal APIs, shortcodes, and features like function calling and real-time audio chat. You can build your own AI tools, automate tasks, or create AI-driven SaaS applications on top of WordPress. AI Engine supports a range of model providers, including OpenAI, Anthropic, Google, and Hugging Face. You can explore ideas in the AI Playground, use Copilot in the editor, or let an AI agent manage your content through MCP. [Get started](https://ai.thehiddendocs.com/services/pinecone/) # 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 is 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 connects these systems to Pinecone. The connector fetches data from the connected source, embeds the data using a large language model (LLM), and then upserts it into Pinecone. You can use it with Airbyte's source connectors for use cases like semantic search and recommendation systems. [Get started](https://docs.airbyte.com/integrations/destinations/pinecone) [View setup guide](https://www.pinecone.io/learn/series/airbyte/) ## Resources * [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/) # Amazon Bedrock Source: https://docs.pinecone.io/integrations/amazon-bedrock Use Pinecone as the vector store for a Knowledge Base for Amazon Bedrock, then create a Bedrock agent that retrieves your data for RAG on AWS. You can select Pinecone as a Knowledge Base for [Amazon Bedrock](https://aws.amazon.com/bedrock/), a fully managed service from Amazon Web Services (AWS) for building GenAI applications. Pinecone Database helps companies reduce hallucinations, one of the biggest challenges in deploying GenAI solutions. With Pinecone, companies can store and search their own data, find the most relevant, up-to-date information, and send that context to large language models (LLMs) with every query. This workflow is called retrieval-augmented generation (RAG). With Pinecone, RAG helps search and GenAI applications return relevant, accurate, and fast responses to end users. With Knowledge Bases for Amazon Bedrock, you can integrate your enterprise data into Amazon Bedrock and use Pinecone as the vector store for your GenAI applications. Pinecone helps those applications in the following ways: * Pinecone searches through data in milliseconds. Metadata filters and support for sparse-dense vectors in a single index improve relevance, so results are quick, accurate, and grounded across diverse search tasks. * You can start for free on the Starter plan and scale usage with transparent usage-based pricing. Add or remove resources to meet your desired capacity and performance, upwards of billions of embeddings. * You can launch, use, and scale your AI solution without maintaining infrastructure, monitoring services, or troubleshooting algorithms. Pinecone meets the security and operational requirements of enterprises. [Try free with AWS](https://aws.amazon.com/marketplace/pp/prodview-xhgyscinlz4jk?trk=8d276e92-b310-40ce-908f-23a198ca7ffc\&sc_channel=el\&source=pinecone%20systems) ## Agents for Amazon Bedrock In Bedrock, users interact with agents, which combine the natural language interface of the supported LLMs with that of a knowledge base. Bedrock's Knowledge Base feature uses the supported LLMs to generate embeddings from the original data source. These embeddings are stored in Pinecone, and Bedrock uses the Pinecone index to retrieve semantically relevant content when a user queries the agent. > [!NOTE] > > The LLM used for embeddings can be different from the one used for natural language generation. For example, you can use Amazon Titan to generate embeddings and Anthropic's Claude to generate natural language responses. You can also configure Agents for Amazon Bedrock to execute various actions while responding to a user's query. This guide doesn't cover that functionality. ## Knowledge Bases for Amazon Bedrock A Bedrock knowledge base ingests raw text data or documents found in Amazon S3, embeds the content, and upserts the embeddings into Pinecone. Then, a Bedrock agent can interact with the knowledge base to retrieve the most semantically relevant content for a user's query. The Knowledge Base feature helps you improve your AI models' performance. With Bedrock's LLMs and Pinecone, you can integrate your data from AWS storage solutions and improve the accuracy and relevance of your AI models. This guide walks through creating a Knowledge Base for Amazon Bedrock and an agent that retrieves information from it. ![](https://mintcdn.com/pinecone/9qvQp5nU6duJvusQ/images/AWS_Bedrock_Specific.png?fit=max\&auto=format\&n=9qvQp5nU6duJvusQ\&q=85\&s=f63ffcbacba8c0fbf31eeadd78a90cb5) ## Setup guide ### 1. Create a Pinecone index The knowledge base stores data in a Pinecone index. Decide which [supported embedding model](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html) to use with Bedrock before you create the index, because your index's dimensions must match the model's. For example, the AWS Titan Text Embeddings V2 model can use dimension sizes 1024, 384, and 256. After you sign up for Pinecone, follow the [quickstart guide](/guides/get-started/quickstart) to create your Pinecone index and retrieve your `apiKey` and index host from the [Pinecone console](https://app.pinecone.io). > [!NOTE] > > Your index must have the same dimensions as the model you'll later select for creating your embeddings. Also, your index must be empty. All data must be ingested through Bedrock's sync process. ### 2. Set up your data source #### Set up secrets After you set up your Pinecone index, create a secret in [AWS Secrets Manager](https://console.aws.amazon.com/secretsmanager/newsecret): 1. In the **Secret type** section, select **Other type of secret**. 2. In the **Key/value pairs** section, enter a key-value pair for the Pinecone API key name and its respective value. For example, use `apiKey` and the API key value. ![](https://mintcdn.com/pinecone/9qvQp5nU6duJvusQ/images/bedrock/kv.png?fit=max\&auto=format\&n=9qvQp5nU6duJvusQ\&q=85\&s=78ec35c6ece3f8c3a636f5c5de531fb2) 3. Click **Next**. 4. Enter a **Secret name** and **Description**. 5. Click **Next** to save your key. 6. On the **Configure rotation** page, select all the default options in the next screen, and click **Next**. 7. Click **Store**. 8. Click the new secret you created and save the secret ARN for a later step. #### Set up S3 The knowledge base draws on data saved in S3. This example uses a [sample of research papers](https://huggingface.co/datasets/jamescalam/ai-arxiv2-semantic-chunks) obtained from a dataset. Bedrock embeds this data and then saves it in Pinecone. Follow these steps to set up S3: 1. Create a new general purpose bucket in [Amazon S3](https://console.aws.amazon.com/s3/home). 2. After the bucket is created, upload a CSV file. > [!NOTE] > > The CSV file must have a field for text that will be embedded, and a field for metadata to upload with each embedded text. 3. Save your bucket's address (`s3://…`) for the following configuration steps. ### 3. Create a Bedrock knowledge base To [create a Bedrock knowledge base](https://console.aws.amazon.com/bedrock/home?#/knowledge-bases/create-knowledge-base), use the following steps: 1. Enter a **Knowledge Base name**. 2. In the **Choose data source** section, select **Amazon S3**. 3. Click **Next**. 4. On the **Configure data source** page, enter the **S3 URI** for the bucket you created. 5. If you don't want to use the default chunking strategy, select a chunking strategy. 6. Click **Next**. ### 4. Connect Pinecone to the knowledge base Next, select an embedding model to configure with Bedrock, and configure the data sources: 1. Select the embedding model you decided on earlier. 2. For the **Vector database**, select **Choose a vector store you have created** and select **Pinecone**. 3. Select the checkbox that authorizes AWS to access your Pinecone index. > [!NOTE] > > Ensure your Pinecone index is empty before proceeding. Bedrock can't work with indexes that contain existing data. All data must be ingested through Bedrock's sync process. 4. For the **Endpoint URL**, enter the Pinecone index host retrieved from the Pinecone console. 5. For the **Credentials secret ARN**, enter the secret ARN you created earlier. 6. In the **Metadata field mapping** section, enter the **Text field name** you want to embed and the **Bedrock-managed metadata field name** that Bedrock uses for metadata it manages (e.g., `metadata`). 7. Click **Next**. 8. Review your selections and complete the creation of the knowledge base. 9. On the [Knowledge Bases](https://console.aws.amazon.com/bedrock/home?#/knowledge-bases) page, select the knowledge base you just created to view its details. 10. Click **Sync** for the newly created data source. > [!NOTE] > > Whenever you add new data, sync the data source to start the ingestion workflow, which converts your Amazon S3 data into vector embeddings and upserts them into your Pinecone index. Depending on the amount of data, this can take some time. ### 5. Create and link an agent to Bedrock Lastly, [create an agent](https://console.aws.amazon.com/bedrock/home?#/agents) that will use the knowledge base for retrieval: 1. Click **Create Agent**. 2. Enter a **Name** and **Description**. 3. Click **Create**. 4. Select the LLM provider and model you'd like to use. 5. Provide instructions for the agent. These define what the agent is trying to accomplish. 6. In the **Knowledge Bases** section, select the knowledge base you created. 7. Prepare the agent by clicking **Prepare** near the top of the builder page. 8. Test the agent after preparing it to verify it's using the knowledge base. 9. Click **Save and exit**. Your agent is now set up. The following sections show how to deploy and interact with it. #### Create an alias for your agent To deploy the agent, create an alias for it that points to a specific version of the agent. After you create the alias, it appears in the agent view. 1. On the [Agents](https://console.aws.amazon.com/bedrock/home?#/agents) page, select the agent you created. 2. Click **Create Alias**. 3. Enter an **Alias name** and **Description**. 4. Click **Create alias**. #### Test the Bedrock agent To test the newly created agent, open it and use the playground on the right of the screen. This example uses a dataset of research papers as its source data. You can ask a question about those papers and get a detailed response, this time from the deployed version. ![](https://mintcdn.com/pinecone/9qvQp5nU6duJvusQ/images/bedrock/alias-testing-query.png?fit=max\&auto=format\&n=9qvQp5nU6duJvusQ\&q=85\&s=bcc833861883b073434c43817f0c5c84) Inspect the trace to see which chunks the agent used and to diagnose issues with responses. ![](https://mintcdn.com/pinecone/9qvQp5nU6duJvusQ/images/bedrock/alias-testing-trace.png?fit=max\&auto=format\&n=9qvQp5nU6duJvusQ\&q=85\&s=e8aa228c1ad062975f12e56ea22cd899) ## Resources * [Pinecone as a Knowledge Base for Amazon Bedrock](https://www.pinecone.io/blog/amazon-bedrock-integration/) # Amazon SageMaker Source: https://docs.pinecone.io/integrations/amazon-sagemaker Combine Amazon SageMaker with Pinecone to host LLMs and embedding models for scalable retrieval-augmented generation and vector search workloads. Amazon SageMaker is a fully managed service that brings together a broad set of tools for machine learning (ML). With SageMaker, you can build, train, and deploy ML models at scale in one integrated development environment (IDE). SageMaker supports governance requirements with simplified access control and transparency over your ML projects. Amazon SageMaker offers access to hundreds of pretrained models, including publicly available foundational models (FMs), and you can build your own FMs with purpose-built tools to fine-tune, experiment, retrain, and deploy FMs. You can use Amazon SageMaker and Pinecone together for retrieval-augmented generation (RAG) use cases. The integration uses Amazon SageMaker to compute and host large language models (LLMs), and uses Pinecone as the knowledge base that keeps the LLMs up to date with the latest information, reducing the likelihood of hallucinations. [Get started](https://www.pinecone.io/learn/sagemaker-rag/) ## Resources * [Mitigate hallucinations through Retrieval Augmented Generation using Pinecone vector database & Llama-2 from Amazon SageMaker JumpStart](https://aws.amazon.com/blogs/machine-learning/mitigate-hallucinations-through-retrieval-augmented-generation-using-pinecone-vector-database-llama-2-from-amazon-sagemaker-jumpstart/) # 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 transfers results from Actors to a Pinecone index, so you can use data extracted from the web for retrieval-augmented generation (RAG) or semantic search. [Get started](https://docs.apify.com/platform/integrations/pinecone) # 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, and presentations. It's built for RAG and generative AI applications, and Aryn reports 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. The Pinecone integration with Aryn lets you chunk documents, create vector embeddings, and load the results into Pinecone. 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 the first step in a Sycamore data processing pipeline. It identifies and extracts parts of documents, like text, tables, and images, using a vision segmentation AI model trained on hundreds of thousands of human-annotated documents. [Get started](https://sycamore.readthedocs.io/en/stable/sycamore/connectors/pinecone.html) # AWS Marketplace Source: https://docs.pinecone.io/integrations/aws-marketplace Subscribe to Pinecone through AWS Marketplace for centralized procurement, pay-as-you-go billing, and consolidated invoicing on your AWS account. Access Pinecone through its AWS Marketplace listing. AWS Marketplace lets you manage Pinecone and other third-party software from a centralized location, and simplifies software licensing and procurement with flexible pricing options and multiple deployment methods. You can set up pay-as-you-go billing for a Pinecone organization through AWS Marketplace. [Try free with AWS](https://aws.amazon.com/marketplace/pp/prodview-xhgyscinlz4jk?trk=8d276e92-b310-40ce-908f-23a198ca7ffc\&sc_channel=el\&source=pinecone%20systems) [View setup guide](/admin/billing/upgrade-billing-plan) # Box Source: https://docs.pinecone.io/integrations/box Connect Box folders to Pinecone Database to embed documents with Pinecone's standalone embedding and build RAG agents and semantic search over Box content. [Box](https://www.box.com/) is a cloud content management platform. This integration connects a Box account to Pinecone Database and generates embeddings from content stored in a specific Box account and folder. By default, the integration uses Pinecone's standalone embedding and OpenAI for the LLM. You can use the integration within a larger AI agent or workflow. [Get started](https://developer.box.com/ai/vector-databases/pinecone) # 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) adds Pinecone skills, the Pinecone MCP server, and slash commands to Claude Code in your terminal. Use natural language to manage indexes, query data, build RAG applications, and create document Q\&A assistants, with up-to-date Pinecone API knowledge. [View on GitHub](https://github.com/pinecone-io/pinecone-claude-code-plugin) ## Features * Built-in skills cover index management, semantic search, full-text search, assistant creation, and more. * The integrated MCP server runs Pinecone operations directly from Claude Code. * Slash commands like `/pinecone:quickstart` and `/pinecone:query` give you quick access to skills. * Assistant commands work from natural language, without explicit slash commands. ## Prerequisites * A [Pinecone API key](https://app.pinecone.io/organizations/-/keys) * [Claude Code](https://claude.ai/code) installed with access to the [official Anthropic marketplace](https://code.claude.com/docs/en/discover-plugins#official-anthropic-marketplace) * [Node.js](https://nodejs.org/) installed (`npx` must be on your `PATH`) * [uv](https://docs.astral.sh/uv/getting-started/installation/) installed (required to run the bundled Python scripts, including the quickstart skill) * [Pinecone CLI](/reference/cli/quickstart) installed (optional, for advanced operations) ## Installation **1. Set your API key** ```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). **2. Install the plugin** From your terminal: ```shell theme={null} claude plugin install pinecone ``` Or from within Claude Code: ```text theme={null} /plugin install pinecone ``` **3. Restart Claude Code** 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 that walks you through creating an index, upserting data, and running a 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. Requires Python SDK v10.0.0 or later. | | 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/agents/mcp-server). ## Resources * [GitHub repository](https://github.com/pinecone-io/pinecone-claude-code-plugin) * [Pinecone MCP server guide](/guides/agents/mcp-server) * [Claude Code documentation](https://docs.claude.com/en/docs/claude-code/quickstart) # Cloudera AI Source: https://docs.pinecone.io/integrations/cloudera Integrate Cloudera AI with Pinecone to run distributed Spark and Python embedding pipelines and power scalable RAG and vector search on enterprise data. [Cloudera AI](https://www.cloudera.com/) is an enterprise data cloud service for scalable, secure machine learning and AI workflows. It uses Python, Apache Spark, R, and other runtimes for distributed data processing, so you can create, ingest, and update vector embeddings at scale. Integrating Pinecone with Cloudera AI adds vector search to retrieval-augmented generation (RAG) applications built on Cloudera AI. Pinecone retrieves relevant context from large datasets to ground model output in relevant, real-time data, with low query latency, dynamic index updates, and scale to billions of vector embeddings. Cloudera AI integrates with the rest of the Cloudera ecosystem, so data flows across the stages of machine learning and AI pipelines. It offers interactive sessions, collaborative projects, model hosting, and application hosting in a Python-centric development environment. You can use its project and session management features to prototype, develop, and deploy RAG applications that combine Cloudera AI's hosted models with retrieval from Pinecone. Cloudera's Accelerators for Machine Learning Projects (AMPs) are prebuilt projects that do the development work of deploying RAG architectures for you. This AMP is a prototype that fully integrates Pinecone into a RAG use case and shows semantic search with RAG at scale. [Get started](https://github.com/cloudera/CML_AMP_Intelligent-QA-Chatbot-with-NiFi-Pinecone-and-Llama2) ## Resources * [Python script](https://github.com/cloudera/CML_llm-hol/blob/main/2_populate_vector_db/pinecone_vectordb_insert.py) - Example of creating vectors in Pinecone * [Jupyter notebook](https://github.com/cloudera/CML_llm-hol/blob/main/3_query_vector_db/pinecone_vectordb_query.ipynb) - Example of querying a Pinecone index # Codex plugin Source: https://docs.pinecone.io/integrations/codex Install the official Pinecone plugin for Codex to manage indexes, run vector search, and build RAG assistants from Codex using skills and MCP tools. The official Pinecone plugin for [Codex](https://developers.openai.com/codex) adds Pinecone skills and the Pinecone MCP server to your Codex sessions. Use natural language to manage indexes, query data, build RAG applications, and create document Q\&A assistants, with up-to-date Pinecone API knowledge. [View on GitHub](https://github.com/pinecone-io/pinecone-codex-plugin) ## Features * Built-in skills cover index management, semantic search, full-text search, assistant creation, and more. * The bundled MCP server runs Pinecone operations directly from Codex, with no extra setup. * Codex invokes the right skill based on your conversation. ## Prerequisites * A [Pinecone API key](https://app.pinecone.io/organizations/-/keys) * The [ChatGPT desktop app](https://developers.openai.com/codex/app) (which includes Codex) or the [Codex CLI](https://developers.openai.com/codex/cli) * A local Codex session, since the plugin runs on your machine and doesn't work in Codex cloud tasks * [Node.js](https://nodejs.org/) installed and on your `PATH` (required for the bundled MCP server) * [uv](https://docs.astral.sh/uv/getting-started/installation/) installed (required to run the bundled Python scripts, including the quickstart skill) * [Pinecone CLI](/reference/cli/quickstart) installed (optional, enables the `pinecone:cli` skill) ## Installation Install the plugin from the plugin directory or the command line, then set your API key and launch Codex. **1. Add the plugin to Codex** > [tab] Plugin directory > > Open the [Pinecone plugin](https://chatgpt.com/codex/open-app?target=plugin\&plugin_id=plugins_6ab1957381a88191b41034b7a47dc51f) in the ChatGPT desktop app, then click **Install plugin**. > > To find it yourself instead: > > 1. In the ChatGPT desktop app, click your profile in the bottom left, then click **Settings**. > > 2. In the left navigation, click **Plugins**. > > You'll see a list of the plugins you already have. > > 3. Click **Browse directory**. > > 4. Search for Pinecone, then select **Pinecone**. > > 5. Click **Install plugin**. > > For more about installing plugins, see [Plugins in ChatGPT](https://help.openai.com/en/articles/20001256-plugins-in-chatgpt) in the OpenAI Help Center. > [tab] Command line > > 1. Add the Pinecone marketplace: > > ```shell theme={null} > codex plugin marketplace add pinecone-io/pinecone-codex-plugin > ``` > > 2. Install the plugin: > > ```shell theme={null} > codex plugin add pinecone --marketplace pinecone-codex-plugins > ``` > > 3. Confirm the plugin is installed: > > ```shell theme={null} > codex plugin list | grep pinecone > ``` **2. Set your API key and launch Codex** Installing the plugin doesn't set your API key. Codex reads it from the environment it launches in. > [tab] CLI (macOS, Linux) > > 1. Set the key in the same shell where you run Codex: > > ```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). To keep it across terminal sessions, add the line to your shell profile, such as `~/.zshrc`. > > 2. Start Codex: > > ```shell theme={null} > codex > ``` > [tab] CLI (Windows) > > If you run Codex in WSL, use the **CLI (macOS, Linux)** tab instead. > > 1. Set the key in the same PowerShell session where you run Codex: > > ```powershell theme={null} > $env:PINECONE_API_KEY="YOUR_API_KEY" > ``` > > Replace `YOUR_API_KEY` with your [Pinecone API key](https://app.pinecone.io/organizations/-/keys). This lasts for the current session only. To keep it across sessions, run `setx PINECONE_API_KEY "YOUR_API_KEY"` and open a new terminal. > > 2. Start Codex: > > ```powershell theme={null} > codex > ``` > [tab] Desktop app (macOS) > > 1. Set the key for all macOS apps: > > ```shell theme={null} > launchctl setenv PINECONE_API_KEY "YOUR_API_KEY" > ``` > > Replace `YOUR_API_KEY` with your [Pinecone API key](https://app.pinecone.io/organizations/-/keys). This setting doesn't persist after you restart your Mac, so run it again after each restart. > > 2. Quit the ChatGPT desktop app completely, then reopen it. > [tab] Desktop app (Windows) > > 1. Set the key for your Windows user account: > > ```powershell theme={null} > setx PINECONE_API_KEY "YOUR_API_KEY" > ``` > > Replace `YOUR_API_KEY` with your [Pinecone API key](https://app.pinecone.io/organizations/-/keys). `setx` persists across restarts. > > 2. Quit the ChatGPT desktop app completely, then reopen it. **3. Run the quickstart** In a new Codex session, ask: ```text theme={null} Use Pinecone's quickstart to create an index, add sample data, and run my first search. ``` Codex invokes the `pinecone:quickstart` skill, which creates an index, loads sample data, and runs a search. ## Available skills Codex picks the right skill based on what you ask. To call a skill directly, type `$` followed by its name, such as `$pinecone:quickstart`. To bring in the whole plugin, mention `@pinecone`. | Skill | Description | | - | - | | `pinecone:help` | Overview of all skills and setup requirements. Start here. | | `pinecone:quickstart` | Walks you through creating an index, upserting data, and running a query. | | `pinecone:query` | Search integrated indexes using natural language via the Pinecone MCP server. | | `pinecone:assistant` | Create, upload, sync, and chat with Pinecone Assistants for document Q\&A with citations. | | `pinecone:cli` | Guide for using the Pinecone CLI (`pc`) from the terminal. | | `pinecone:full-text-search` | Create, ingest into, and query a Pinecone full-text-search (FTS) index. Requires Python SDK v10.0.0 or later. | | `pinecone:n8n` | Build [n8n](/integrations/n8n) workflows with the Pinecone Assistant node or Pinecone Vector Store, including best practices and full workflow JSON generation. | | `pinecone:mcp` | Reference for all Pinecone MCP server tools. | | `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/agents/mcp-server). ## Troubleshooting > [accordion] API key not found or 401 errors > > Check whether your API key is set in the environment Codex runs in: > > * For the CLI on macOS or Linux, in the same shell where you run `codex`, run `[ -n "$PINECONE_API_KEY" ] && echo "set" || echo "not set"`. If it prints `not set`, set the key again. > * For the CLI on Windows, in the same PowerShell session where you run `codex`, run `if ($env:PINECONE_API_KEY) { "set" } else { "not set" }`. If it prints `not set`, set the key again. > * For the desktop app on macOS, run `launchctl getenv PINECONE_API_KEY`. If it returns nothing, set the key again, then quit and reopen the app. > * For the desktop app on Windows, run `[Environment]::GetEnvironmentVariable("PINECONE_API_KEY", "User")` in PowerShell. If it returns nothing, set the key again, then quit and reopen the app. > [accordion] MCP server not responding > > Make sure Node.js is on your `PATH` and your API key is valid, then restart Codex. > [accordion] The query skill returns no results > > The `pinecone:query` skill works only with integrated indexes, which use a Pinecone-hosted embedding model. For indexes that use external embeddings, use the `pinecone:cli` skill or the MCP tools directly. > [accordion] Skill script errors > > Run `uv --version` to confirm `uv` is installed. If it's missing, install it and restart your terminal. ## Resources * [GitHub repository](https://github.com/pinecone-io/pinecone-codex-plugin) * [Codex documentation](https://developers.openai.com/codex) * [Plugins in ChatGPT (OpenAI Help Center)](https://help.openai.com/en/articles/20001256-plugins-in-chatgpt) * [Pinecone MCP server guide](/guides/agents/mcp-server) # 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 is a cloud-native data streaming platform for connecting and processing your data in real time. Confluent's Kafka Connect is a tool for streaming data between Apache Kafka and other data systems, and you can use it to 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 index. [Get started](https://www.confluent.io/hub/confluentinc/kafka-connect-pinecone-sink) [View setup guide](https://docs.confluent.io/cloud/current/connectors/cc-pinecone-sink.html) # Context Data Source: https://docs.pinecone.io/integrations/context-data Use Context Data with Pinecone to build no-code flows from Postgres, S3, Salesforce, and more, embedding data and querying indexes in Query Studio. [Context Data](https://contextdata.ai/) lets you build end-to-end data flows in a no-code web interface. With the Pinecone integration, you can connect to data sources such as PostgreSQL, MySQL, Amazon S3, and Salesforce, embed the data, and write the results to Pinecone. You can also trigger these flows and run them on a schedule you define. Before writing to Pinecone, you can transform data with aggregations, joins, and feature engineering using SQL common table expressions. You can also chat with your Pinecone indexes from Context Data's privacy-focused Query Studio. [Get started](https://context-data.gitbook.io/context-data-1/adding-target-connections#add-a-pinecone-target-connection) # 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/) adds Pinecone skills, the Pinecone MCP server, and slash commands to your editor. Use natural language to manage indexes, query data, build RAG applications, and create document Q\&A assistants, with up-to-date Pinecone API knowledge. [View on GitHub](https://github.com/pinecone-io/pinecone-cursor-plugin) ## Features * Built-in skills cover index management, semantic search, full-text search, assistant creation, and more. * The bundled MCP server (`@pinecone-database/mcp`) runs Pinecone operations directly from Cursor Agent. * Slash commands like `/pinecone-quickstart` and `/pinecone-query` give you quick access to skills. * 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 (required to run the bundled Python scripts, including the quickstart skill) * [Pinecone CLI](/reference/cli/quickstart) installed (optional, enables the `pinecone-cli` skill) ## Installation **1. Set your API key** 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. **2. Install the plugin** In Cursor chat, run: ```text theme={null} /add-plugin pinecone ``` Or install directly from the [Cursor Marketplace](https://cursor.com/marketplace/pinecone). **3. Verify the installation** Open Cursor Agent chat and run `/pinecone-help` to confirm the skills are loaded. You can also check: * Skills are listed under **Agent Decides** in **Cursor Settings > Rules**. * The MCP server is listed in **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 that walks you through creating an index, upserting data, and running a 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. | | 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/agents/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/agents/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, you can horizontally scale a cluster to handle computationally intensive tasks like vector embedding, where parallelization can save many hours of computation time and resources. Using GPUs with Spark can produce even better results, because it combines the fast computation of a GPU with parallelization. Use Databricks and Pinecone to create, ingest, and update vector embeddings at scale. [Get started](/reference/tools/pinecone-spark-connector) ## 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](/admin/projects/projects-overview#api-keys) ### 1. Install the Spark-Pinecone connector > [tab] Databricks platform > > 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.2.0/spark-pinecone-uberjar.jar > ``` > > > [!NOTE] > > > > Databricks platform users must use the Pinecone assembly jar listed above to ensure that the proper dependecies are installed. > > 3. Click **Install**. > [tab] Databricks on AWS > > 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.2.0/spark-pinecone-uberjar.jar > ``` > > 3. Click **Install**. > [tab] Databricks on GCP / Azure > > 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.2.0/). > 2. Select **Workspace** as the **Library Source**. > 3. Upload the JAR file. > 4. Click **Install**. ### 2. Load the dataset into partitions This guide uses a collection of news articles from the Hugging Face Datasets library as the example dataset. To load it, follow these steps: 1. [Create a new notebook](https://docs.databricks.com/en/notebooks/notebooks-manage.html#create-a-notebook) attached to your cluster. 2. Install dependencies: ```shell Shell theme={null} %pip install datasets transformers pinecone torch ``` 3. Load the dataset: ```Python Python theme={null} from datasets import 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's conceptually equivalent to a table in a relational database or a dataframe in R/Python, but with richer optimizations under the hood. 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 embeddings Generate an embedding for each document, and then convert the results to the schema Pinecone expects: 1. Create a user-defined function (UDF) 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, LongType 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. Store the embeddings Write the embeddings to a Pinecone index with the Spark-Pinecone connector, and then query the index: 1. Initialize the connection to Pinecone: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec api_key = "YOUR_API_KEY" index_name = "news" pc = Pinecone(api_key=api_key) ``` 2. Create an index for your embeddings. The `dimension` must match the model's output size, which is 384 for all-MiniLM-L6-v2: ```Python Python theme={null} if not pc.has_index(index_name): pc.create_index( name=index_name, dimension=384, 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() ) ``` 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/2026-07/data-plane/query) returns the IDs of the most similar records in the index, along with their similarity scores: ```Python Python theme={null} index = pc.Index(index_name) index.query( vector=[0.3] * 384, top_k=3, include_values=True ) ``` > [!NOTE] > > If you want to make a query with a text string (e.g., `"Summarize this article"`), use the [`search` endpoint](/reference/api/2026-07/data-plane/search_records) on a legacy integrated index. # 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 moves data from these systems to Pinecone and keeps it up to date. It updates source data incrementally, which minimizes the credits you use to get embeddings from providers before pushing them to Pinecone. You can use Estuary's Pinecone connector for use cases like LLM-based search across your organization's data and recommendation systems. You can set it up in 5 minutes without engineering effort. [Get started](https://docs.estuary.dev/reference/Connectors/materialization-connectors/pinecone/) # 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 is a low-code platform for building, deploying, and managing data workflows. You create workflows with SQL and pre-configured processing nodes, and you can combine data processing, microservice interactions, and large language model (LLM) inference in a single environment without extensive coding or infrastructure knowledge. Fleak runs workflows on serverless, autoscaling HTTP API endpoints. By integrating Pinecone into Fleak, you can use your vector data to enrich your workflows without additional engineering overhead, for use cases like data-driven decision-making, analytics, and AI-driven insights. [Get started](https://docs.fleak.ai/workflowbuilder/nodes/pinecone_retrieval) # 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 platform for developing LLM apps. It supports integrations with dozens of systems, including databases and chat models. The Pinecone integration with Flowise lets you build RAG apps that upsert and query documents. [Get started](https://docs.flowiseai.com/integrations/langchain/vector-stores/pinecone) # 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 a "data to outcome" platform that enterprises use to build and operationalize data and AI solutions at scale. Gathr reads from and writes to Pinecone using a built-in connector. Gathr combines data engineering, machine learning, generative AI, analytics, and process automation on a single platform, with no-code application development. Teams can use it to ingest petabyte-scale data in real time and orchestrate thousands of data processing pipelines. Gathr also supports generative AI use cases like document summarization, sentiment analysis, next best action, insider threat detection, predictive maintenance, and custom chatbots. Use Gathr Gen AI Fabric to build enterprise generative AI solutions on a single platform. It offers building blocks for generative AI solutions, solution templates, and GathrIQ, a data-to-outcome copilot. Its building blocks include integration with vector databases and knowledge graphs, and the Pinecone connector supports use cases that require knowledge graphs. [Get started](https://docs.gathr.one/gathr-saas/docs/components/pinecone/) # Genkit Source: https://docs.pinecone.io/integrations/genkit Use the Genkit Pinecone plugin with Firebase to build AI features with type-safe indexers, embedders, and retrievers for RAG and semantic search apps. [Genkit](https://firebase.google.com/docs/genkit) is a framework from Firebase for building AI features into your apps. The Genkit Pinecone plugin provides indexer, embedder, and retriever abstractions that reduce the work of integrating AI components. With the plugin, you can combine AI models with your own custom logic and data to build AI features for your business. You can also analyze unstructured text, generate creative content, select tasks, and send results back to your app as structured, type-safe objects. The plugin provides a common format for content that supports combinations of text, data, and other media. You can use Genkit for models that perform any generative task, such as image generation, not just LLMs. [Get started](https://firebase.google.com/docs/genkit/plugins/pinecone) # Google Cloud Marketplace Source: https://docs.pinecone.io/integrations/google-cloud-marketplace Subscribe to Pinecone through Google Cloud Marketplace for centralized procurement, pay-as-you-go billing, and consolidated GCP invoicing. Access Pinecone through its Google Cloud Marketplace listing. Google Cloud Marketplace lets you manage Pinecone and other third-party software from a centralized location, and simplifies software licensing and procurement with flexible pricing options and multiple deployment methods. You can set up pay-as-you-go billing for a Pinecone organization through Google Cloud Marketplace. [Get started](https://console.cloud.google.com/marketplace/product/pinecone-public/pinecone) # Haystack Source: https://docs.pinecone.io/integrations/haystack Use deepset Haystack's PineconeDocumentStore to build production NLP pipelines that index, embed, and query documents for question answering and RAG. Haystack is the open-source Python framework by deepset for building custom apps with large language models (LLMs). It lets you try out the latest models in natural language processing (NLP), and it's flexible to work with. Its community of users and builders has helped shape Haystack into a complete framework for building NLP apps for production. You can use the Haystack and Pinecone integration to keep your NLP-driven apps up to date, with Haystack's indexing pipelines to help you prepare and maintain your data. ## Setup guide This guide shows how to integrate Pinecone and the [Haystack library](https://github.com/deepset-ai/haystack) for question answering. It uses OpenAI models to create embeddings and generate answers. ### 1. Install Haystack Install the latest version of Haystack, the Pinecone integration for Haystack, and Hugging Face Datasets. ```shell Shell theme={null} pip install -U "haystack-ai>=3.3.0" "pinecone-haystack>=6.4.1" "datasets" ``` ### 2. Set your API keys The `PineconeDocumentStore` reads your Pinecone API key from the `PINECONE_API_KEY` environment variable, and Haystack's OpenAI components read your OpenAI API key from `OPENAI_API_KEY`. [Create an account](https://app.pinecone.io) to get your free Pinecone API key. ```Python Python theme={null} import os os.environ["PINECONE_API_KEY"] = "YOUR_API_KEY" os.environ["OPENAI_API_KEY"] = "YOUR_OPENAI_API_KEY" ``` ### 3. Initialize the PineconeDocumentStore Initialize a `PineconeDocumentStore`. If the index doesn't exist, the document store creates a serverless index with the dimension, metric, and spec you provide. The dimension matches the `text-embedding-3-small` embedding model used later in this guide. ```Python Python theme={null} from haystack_integrations.document_stores.pinecone import PineconeDocumentStore document_store = PineconeDocumentStore( index="haystack-qa", namespace="squad", dimension=1536, metric="cosine", spec={"serverless": {"cloud": "aws", "region": "us-east-1"}}, ) ``` ### 4. Prepare data Before you add data to the document store, you must download the data and convert it into the Document format that Haystack uses. This guide uses the SQuAD dataset available from Hugging Face Datasets. ```Python Python theme={null} from datasets import load_dataset # load the squad dataset data = load_dataset("rajpurkar/squad", split="train") ``` Next, remove duplicates and unnecessary columns. ```Python Python theme={null} # convert to a pandas dataframe df = data.to_pandas() # select only title and context column df = df[["title", "context"]] # drop rows containing duplicate context passages df = df.drop_duplicates(subset="context") df.head() ``` | | title | context | | - | - | - | | 0 | University_of_Notre_Dame | Architecturally, the school has a Catholic cha... | | 5 | University_of_Notre_Dame | As at most other universities, Notre Dame's st... | | 10 | University_of_Notre_Dame | The university is the major seat of the Congre... | | 15 | University_of_Notre_Dame | The College of Engineering was established in ... | | 20 | University_of_Notre_Dame | All of Notre Dame's undergraduate students are... | Then convert these records into the Document format. ```Python Python theme={null} from haystack import Document docs = [ Document(content=row["context"], meta={"title": row["title"]}) for _, row in df.iterrows() ] ``` This `Document` format contains two fields: `content` for the text content or paragraphs, and `meta` for any additional information you can later use to apply metadata filtering in your search. ### 5. Embed and upsert documents Build an indexing pipeline that creates an embedding for each document with OpenAI's `text-embedding-3-small` model and writes the documents and their embeddings to Pinecone. ```Python Python theme={null} from haystack import Pipeline from haystack.components.embedders import OpenAIDocumentEmbedder from haystack.components.writers import DocumentWriter indexing = Pipeline() indexing.add_component("embedder", OpenAIDocumentEmbedder(model="text-embedding-3-small")) indexing.add_component("writer", DocumentWriter(document_store=document_store)) indexing.connect("embedder.documents", "writer.documents") indexing.run({"embedder": {"documents": docs}}) ``` ### 6. Inspect documents and embeddings You can get documents by their metadata with the `PineconeDocumentStore.filter_documents` method. ```Python Python theme={null} docs_found = document_store.filter_documents( filters={"field": "meta.title", "operator": "==", "value": "Egypt"} ) d = docs_found[0] ``` From here, you can view document content with `d.content` and the document embedding with `d.embedding`. ### 7. Initialize a question-answering pipeline A retrieval-augmented question-answering pipeline contains four components: * a text embedder that creates an embedding for the question * a retriever (`PineconeEmbeddingRetriever`) that finds the most relevant documents in Pinecone * a prompt builder that adds the retrieved documents and the question to a prompt * a generator that answers the question with an LLM This guide uses OpenAI's `gpt-4o-mini` model as the generator. ```Python Python theme={null} from haystack.components.builders import ChatPromptBuilder from haystack.components.embedders import OpenAITextEmbedder from haystack.components.generators.chat import OpenAIChatGenerator from haystack.dataclasses import ChatMessage from haystack_integrations.components.retrievers.pinecone import PineconeEmbeddingRetriever template = [ ChatMessage.from_user( """Answer the question using only the context below. Context: {% for document in documents %} {{ document.content }} {% endfor %} Question: {{ question }} Answer:""" ) ] pipe = Pipeline() pipe.add_component("text_embedder", OpenAITextEmbedder(model="text-embedding-3-small")) pipe.add_component("retriever", PineconeEmbeddingRetriever(document_store=document_store)) pipe.add_component("prompt_builder", ChatPromptBuilder(template=template, required_variables=["question", "documents"])) pipe.add_component("llm", OpenAIChatGenerator(model="gpt-4o-mini")) pipe.connect("text_embedder.embedding", "retriever.query_embedding") pipe.connect("retriever.documents", "prompt_builder.documents") pipe.connect("prompt_builder.prompt", "llm.messages") ``` ### 8. Ask questions Define a helper function that runs the pipeline and prints the answer along with the title and score of each retrieved document. The `top_k` parameter sets how many documents the retriever passes to the LLM. ```Python Python theme={null} def ask(question, top_k=1): result = pipe.run( { "text_embedder": {"text": question}, "retriever": {"top_k": top_k}, "prompt_builder": {"question": question}, }, include_outputs_from={"retriever"}, ) print("Query:", question) print("Answer:", result["llm"]["replies"][0].text) for doc in result["retriever"]["documents"]: print("Source:", doc.meta["title"], round(doc.score, 3)) ``` Use your QA pipeline to ask a few questions: ```Python Python theme={null} ask("What was Albert Einstein famous for?") ask("How much oil is Egypt producing in a day?") ask("Who founded YouTube?") ``` ```text Response theme={null} Query: What was Albert Einstein famous for? Answer: Albert Einstein was famous for his theories of special relativity and general relativity, as well as his contributions to statistical mechanics, quantum mechanics, and quantum field theory. Source: Modern_history 0.635 Query: How much oil is Egypt producing in a day? Answer: Egypt was producing 691,000 bbl/d of oil. Source: Egypt 0.674 Query: Who founded YouTube? Answer: Hurley and Chen founded YouTube. Source: YouTube 0.636 ``` You can pass more context to the LLM by setting the `top_k` parameter. ```Python Python theme={null} ask("Who was the first person to step foot on the moon?", top_k=3) ``` ```text Response theme={null} Query: Who was the first person to step foot on the moon? Answer: Neil Armstrong was the first person to step foot on the Moon. Source: Space_Race 0.639 Source: Space_Race 0.613 Source: Space_Race 0.516 ``` ### 9. Clean up When you're finished with the index, delete it. ```Python Python theme={null} from pinecone import Pinecone pc = Pinecone() # reads PINECONE_API_KEY pc.delete_index(name="haystack-qa") ``` # Instill AI Source: https://docs.pinecone.io/integrations/instill Wire Pinecone into Instill AI no-code pipelines to upsert, query, and power RAG agents, chatbots, and knowledge bases with vector similarity. Instill AI builds tools for data, models, and pipeline orchestration. Its flagship source-available product, Instill Core, is a no-code and low-code platform for developing, deploying, and managing AI workflows. Instill Core integrates AI models and data sources so you can build AI applications without extensive technical expertise, for use cases that range from predictive analytics and autonomous AI agents to enterprise private knowledge bases and AI assistants. The Pinecone integration with Instill adds Pinecone vector upsert and query tasks to your AI pipelines. To configure the Pinecone component in Instill Core, provide your API key and base URL. You can then query for similar vectors to retrieve the most relevant results, with metadata and similarity scores, or upsert new vectors to keep your datasets up to date. This lets you add knowledge to LLMs through retrieval-augmented generation (RAG) for autonomous agents, chatbots, question-answering systems, and multi-agent systems. [Get started](https://github.com/instill-ai/pipeline-backend/blob/main/pkg/component/data/pinecone/v0/README.mdx) # LangChain Source: https://docs.pinecone.io/integrations/langchain Use Pinecone with LangChain to build RAG apps, agents, and chatbots, and manage embeddings, vector stores, retrievers, and chains for LLM-powered search. LangChain provides modules for managing and optimizing the use of large language models (LLMs) in applications. Its core philosophy is to support data-aware applications where the language model interacts with other data sources and its environment. The framework includes several parts that simplify the application lifecycle: * Write your applications in LangChain or LangChain.js. * Use LangSmith to inspect, test, and monitor your chains so you can keep improving them and deploy with confidence. By integrating Pinecone with LangChain, you can add knowledge to LLMs with retrieval-augmented generation (RAG), which improves what LLMs can do in autonomous agents, chatbots, question-answering, and multi-agent systems. [Get started](https://github.com/langchain-ai/pinecone-serverless) ## Setup guide This guide shows you how to integrate Pinecone Database with [LangChain](https://www.langchain.com/). > [!NOTE] > > This guide shows one of many ways to use LangChain and Pinecone together. For more examples, see the following: > > * [LangChain AI Handbook](https://www.pinecone.io/learn/series/langchain/) > * [Retrieval Augmentation for LLMs](https://github.com/pinecone-io/examples/blob/main/learn/generation/langchain/handbook/05-langchain-retrieval-augmentation.ipynb) > * [Retrieval Augmented Conversational Agent](https://github.com/pinecone-io/examples/blob/main/learn/generation/langchain/handbook/08-langchain-retrieval-agent.ipynb) ## Key concepts The `PineconeVectorStore` class from LangChain lets you interact with Pinecone indexes. You must have an existing Pinecone index before you can create a `PineconeVectorStore` object. ### Initialize a vector store To initialize a `PineconeVectorStore` object, you must provide the name of the Pinecone index and an `Embeddings` object initialized through LangChain. You can initialize a `PineconeVectorStore` object in two ways: 1. Initialize without adding records: ```Python Python theme={null} import os from langchain_pinecone import PineconeVectorStore from langchain_openai import OpenAIEmbeddings os.environ['OPENAI_API_KEY'] = '' os.environ['PINECONE_API_KEY'] = '' index_name = "" embeddings = OpenAIEmbeddings(model="text-embedding-3-small") vectorstore = PineconeVectorStore(index_name=index_name, embedding=embeddings) ``` You can also use the `from_existing_index` method of LangChain's `PineconeVectorStore` class to initialize a vector store. 2. Initialize while adding records: The `from_documents` and `from_texts` methods of LangChain's `PineconeVectorStore` class add records to a Pinecone index and return a `PineconeVectorStore` object. The `from_documents` method accepts a list of LangChain's `Document` class objects, which you can create with LangChain's `CharacterTextSplitter` class. The `from_texts` method accepts a list of strings. As with the first approach, you must provide the name of an existing Pinecone index and an `Embeddings` object. Both of these methods handle the embedding of the provided text data and the creation of records in your Pinecone index. ```Python Python theme={null} import os from langchain_pinecone import PineconeVectorStore from langchain_openai import OpenAIEmbeddings from langchain_community.document_loaders import TextLoader from langchain_text_splitters import CharacterTextSplitter os.environ['OPENAI_API_KEY'] = '' os.environ['PINECONE_API_KEY'] = '' index_name = "" embeddings = OpenAIEmbeddings(model="text-embedding-3-small") # path to an example text file loader = TextLoader("../../modules/state_of_the_union.txt") documents = loader.load() text_splitter = CharacterTextSplitter(chunk_size=1000, chunk_overlap=0) docs = text_splitter.split_documents(documents) vectorstore_from_docs = PineconeVectorStore.from_documents( docs, index_name=index_name, embedding=embeddings ) texts = ["Tonight, I call on the Senate to: Pass the Freedom to Vote Act.", "One of the most serious constitutional responsibilities a President has is nominating someone to serve on the United States Supreme Court.", "One of our nation’s top legal minds, who will continue Justice Breyer’s legacy of excellence."] vectorstore_from_texts = PineconeVectorStore.from_texts( texts, index_name=index_name, embedding=embeddings ) ``` > [!NOTE] > > If you get `Pinecone has no attribute 'from_texts'` or `Pinecone has no attribute 'from_documents'`, your code is calling these methods on the Pinecone SDK's `Pinecone` class instead of LangChain's vector store class. Import `PineconeVectorStore` from `langchain_pinecone`, as shown above. ### Add more records After you initialize a `PineconeVectorStore` object, you can add more records to the underlying Pinecone index (and thus also the linked LangChain object) with the `add_documents` or `add_texts` method. Like `from_documents` and `from_texts`, both of these methods handle the embedding of the provided text data and the creation of records in your Pinecone index. To add documents, use `add_documents`: ```Python Python theme={null} # path to an example text file loader = TextLoader("../../modules/inaugural_address.txt") documents = loader.load() text_splitter = CharacterTextSplitter(chunk_size=1000, chunk_overlap=0) docs = text_splitter.split_documents(documents) vectorstore = PineconeVectorStore(index_name=index_name, embedding=embeddings) vectorstore.add_documents(docs) ``` To add raw text, use `add_texts`: ```Python Python theme={null} vectorstore = PineconeVectorStore(index_name=index_name, embedding=embeddings) vectorstore.add_texts(["More text to embed and add to the index!"]) ``` ### Perform a similarity search A `similarity_search` on a `PineconeVectorStore` object returns a list of LangChain `Document` objects most similar to the query provided. While the `similarity_search` uses a Pinecone query to find the most similar results, this method includes additional steps and returns results of a different type. The `similarity_search` method accepts raw text and automatically embeds it using the `Embedding` object provided when you initialized the `PineconeVectorStore`. You can also provide a `k` value to determine the number of LangChain `Document` objects to return. The default value is `k=4`. ```Python Python theme={null} query = "Who is Ketanji Brown Jackson?" vectorstore.similarity_search(query) ``` You can also apply a metadata filter to your similarity search. The filtering query language is the same as for Pinecone queries, as detailed in [Filtering with metadata](/guides/indexes/index-data-overview#metadata). ```Python Python theme={null} query = "Tell me more about Ketanji Brown Jackson." vectorstore.similarity_search(query, filter={'source': '../../modules/state_of_the_union.txt'}) ``` ### Namespaces Several methods of the `PineconeVectorStore` class support using [namespaces](/guides/indexes/index-data-overview#namespaces). You can also initialize your `PineconeVectorStore` object with a namespace to restrict all further operations to that space. ```Python Python theme={null} index_name = "" embeddings = OpenAIEmbeddings(model="text-embedding-3-small") vectorstore = PineconeVectorStore(index_name=index_name, embedding=embeddings, namespace="example-namespace") ``` If you initialize your `PineconeVectorStore` object without a namespace, you can specify the target namespace within the operation. ```Python Python theme={null} # path to an example text file loader = TextLoader("../../modules/congressional_address.txt") documents = loader.load() text_splitter = CharacterTextSplitter(chunk_size=1000, chunk_overlap=0) docs = text_splitter.split_documents(documents) vectorstore_from_docs = PineconeVectorStore.from_documents( docs, index_name=index_name, embedding=embeddings, namespace="example-namespace" ) vectorstore_from_texts = PineconeVectorStore.from_texts( texts, index_name=index_name, embedding=embeddings, namespace="example-namespace" ) vectorstore_from_docs.add_documents(docs, namespace="example-namespace") vectorstore_from_texts.add_texts(["More text!"], namespace="example-namespace") ``` To search a namespace, pass it to `similarity_search`: ```Python Python theme={null} query = "Who is Ketanji Brown Jackson?" vectorstore.similarity_search(query, namespace="example-namespace") ``` ## Tutorial ### 1. Set up the environment Install the libraries: ```shell Shell theme={null} pip install -qU \ "pinecone[grpc]==7.3.0" \ pinecone-datasets==1.0.2 \ langchain-pinecone==0.2.13 \ langchain-openai==1.6.7 \ langchain==1.4.3 ``` Set your Pinecone and OpenAI API keys as environment variables: ```shell Shell theme={null} export PINECONE_API_KEY="{{YOUR_API_KEY}}" # Get from app.pinecone.io export OPENAI_API_KEY="your-openai-api-key" # Get from platform.openai.com/api-keys ``` Then read the keys in Python: ```Python Python theme={null} import os pinecone_api_key = os.environ.get('PINECONE_API_KEY') openai_api_key = os.environ.get('OPENAI_API_KEY') ``` ### 2. Build the knowledge base Load a sample dataset and prepare it for Pinecone: 1. Load a [sample Pinecone dataset](https://github.com/pinecone-io/pinecone-datasets) into memory: ```Python Python theme={null} import pinecone_datasets dataset = pinecone_datasets.load_dataset('wikipedia-simple-text-embedding-ada-002-100K') len(dataset) ``` ```text Response theme={null} 100000 ``` 2. Reduce the dataset and format it for upserting into Pinecone: ```Python Python theme={null} # we will use rows of the dataset up to index 30_000 dataset.documents.drop(dataset.documents.index[30_000:], inplace=True) # replace the metadata column with blob, which includes the text field dataset.documents.drop(['metadata'], axis=1, inplace=True) dataset.documents.rename(columns={'blob': 'metadata'}, inplace=True) ``` ### 3. Index the data in Pinecone Create an index and upsert the prepared data: 1. Initialize your client connection to Pinecone and create an index. This step uses the Pinecone API key you set as an environment variable [earlier](#set-up-the-environment). ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec import time # configure client pc = Pinecone(api_key=pinecone_api_key) spec = ServerlessSpec(cloud='aws', region='us-east-1') # check for and delete index if already exists index_name = 'langchain-retrieval-augmentation-fast' if pc.has_index(index_name): pc.delete_index(name=index_name) # create a new index pc.create_index( index_name, dimension=1536, # dimensionality of text-embedding-ada-002 metric='dotproduct', spec=spec ) ``` 2. Target the index and check its current stats: ```Python Python theme={null} index = pc.Index(index_name) index.describe_index_stats() ``` ```text Response theme={null} {'dimension': 1536, 'namespaces': {}, 'total_vector_count': 0} ``` The index has a `total_vector_count` of `0` because you haven't added any vectors yet. 3. Upsert the data to Pinecone: ```Python Python theme={null} for batch in dataset.iter_documents(batch_size=100): index.upsert(batch) ``` 4. After the data is indexed, check the index stats again: ```Python Python theme={null} index.describe_index_stats() ``` ```text Response theme={null} {'dimension': 1536, 'namespaces': {'': {'vector_count': 30000}}, 'total_vector_count': 30000} ``` ### 4. Initialize a LangChain vector store Now that you've built your Pinecone index, initialize a LangChain vector store that uses it. This step uses the OpenAI API key you set as an environment variable [earlier](#set-up-the-environment). OpenAI is a paid service, so running the rest of this tutorial may incur a small cost. 1. Initialize a LangChain embedding object: ```Python Python theme={null} from langchain_openai import OpenAIEmbeddings # get openai api key from platform.openai.com model_name = 'text-embedding-ada-002' embeddings = OpenAIEmbeddings( model=model_name, openai_api_key=openai_api_key ) ``` 2. Initialize the LangChain vector store: The `text_field` parameter sets the name of the metadata field that stores the raw text when you upsert records using a LangChain operation such as `vectorstore.from_documents` or `vectorstore.add_texts`. This metadata field is used as the `page_content` in the `Document` objects retrieved from query-like LangChain operations such as `vectorstore.similarity_search`. If you don't specify a value for `text_field`, it defaults to `"text"`. ```Python Python theme={null} from langchain_pinecone import PineconeVectorStore text_field = "text" vectorstore = PineconeVectorStore( index, embeddings, text_field ) ``` 3. Query the vector store directly using `vectorstore.similarity_search`: ```Python Python theme={null} query = "who was Benito Mussolini?" vectorstore.similarity_search( query, # our search query k=3 # return 3 most relevant docs ) ``` ```text Response theme={null} [Document(page_content='Benito Amilcare Andrea Mussolini KSMOM GCTE (29 July 1883 – 28 April 1945) was an Italian politician and journalist...', metadata={'chunk': 0.0, 'source': 'https://simple.wikipedia.org/wiki/Benito%20Mussolini', 'title': 'Benito Mussolini', 'wiki-id': '6754'}), Document(page_content='Fascism as practiced by Mussolini\nMussolini\'s form of Fascism, "Italian Fascism"- unlike Nazism, the racist ideology...', metadata={'chunk': 1.0, 'source': 'https://simple.wikipedia.org/wiki/Benito%20Mussolini', 'title': 'Benito Mussolini', 'wiki-id': '6754'}), Document(page_content='Veneto was made part of Italy in 1866 after a war with Austria. Italian soldiers won Latium in 1870. That was when...', metadata={'chunk': 5.0, 'source': 'https://simple.wikipedia.org/wiki/Italy', 'title': 'Italy', 'wiki-id': '363'})] ``` All of these sample results are relevant. You can also use the vector store for other tasks. One that LangChain supports well is generative question answering (GQA). ### 5. Use Pinecone and LangChain for RAG In RAG, you pass the query to an LLM as a question, and the LLM must answer it based on the information it gets from the vector store. Follow these steps: 1. Build a RAG chain that retrieves context from the vector store and passes it to the LLM with the question: ```Python Python theme={null} from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser from langchain_core.runnables import RunnablePassthrough # completion llm llm = ChatOpenAI( openai_api_key=openai_api_key, model_name='gpt-4o-mini', temperature=0.0 ) retriever = vectorstore.as_retriever() prompt = ChatPromptTemplate.from_template( "Answer the question based only on the following context:\n\n" "{context}\n\n" "Question: {question}" ) def format_docs(docs): return "\n\n".join(doc.page_content for doc in docs) rag_chain = ( {"context": retriever | format_docs, "question": RunnablePassthrough()} | prompt | llm | StrOutputParser() ) rag_chain.invoke(query) ``` ```text Response theme={null} Benito Mussolini was an Italian politician and journalist who served as the Prime Minister of Italy from 1922 until 1943. He was the leader of the National Fascist Party and is known for creating the ideology of Fascism... ``` 2. To include the sources the LLM uses to answer your question, return the retrieved documents alongside the answer: ```Python Python theme={null} from langchain_core.runnables import RunnableParallel rag_chain_with_sources = RunnableParallel( {"docs": retriever, "question": RunnablePassthrough()} ).assign( answer=( {"context": lambda x: format_docs(x["docs"]), "question": lambda x: x["question"]} | prompt | llm | StrOutputParser() ) ) result = rag_chain_with_sources.invoke(query) { "question": result["question"], "answer": result["answer"], "sources": sorted({doc.metadata["source"] for doc in result["docs"]}), } ``` ```text Response theme={null} {'question': 'who was Benito Mussolini?', 'answer': "Benito Mussolini was an Italian politician and journalist who served as the Prime Minister of Italy from 1922 until 1943. He was the leader of the National Fascist Party and is known for creating the ideology of Fascism...", 'sources': ['https://simple.wikipedia.org/wiki/Benito%20Mussolini', ...]} ``` ### 6. Clean up When you no longer need the index, use the `delete_index` operation to delete it: ```Python Python theme={null} pc.delete_index(name=index_name) ``` ## Resources * [LangChain AI Handbook](https://www.pinecone.io/learn/series/langchain/) # LlamaIndex Source: https://docs.pinecone.io/integrations/llamaindex Use Pinecone with LlamaIndex to build RAG pipelines that ingest documents, structure private data, and run semantic search and question answering. LlamaIndex is a framework for connecting data sources to LLMs, with its chief use case being the end-to-end development of retrieval-augmented generation (RAG) applications. LlamaIndex provides abstractions to ingest, structure, and access private or domain-specific data so you can inject it safely and reliably into LLMs for more accurate text generation. It's available in Python and TypeScript. Integrate Pinecone Database with LlamaIndex to build semantic search and RAG applications. ## Setup guide This guide shows you how to use LlamaIndex and Pinecone to both perform traditional semantic search and build a RAG pipeline. Specifically, you'll do the following: * Load, transform, and vectorize sample data with LlamaIndex * Index and store the vectorized data in Pinecone * Search the data in Pinecone and use the results to augment an LLM call * Evaluate the answer you get back from the LLM To run this guide in your browser, see the [LlamaIndex notebook](https://colab.research.google.com/github/pinecone-io/examples/blob/main/learn/generation/llama-index/using-llamaindex-with-pinecone.ipynb). > [!NOTE] > > This guide shows one of many ways to use LlamaIndex as part of a RAG pipeline. See LlamaIndex's section on [Advanced RAG](https://developers.llamaindex.ai/python/framework/optimizing/advanced_retrieval/advanced_retrieval/) to learn more about what's possible. ### 1. Set up the environment Install the libraries: ```shell Shell theme={null} pip install -qU \ pinecone==9.1.0 \ llama-index==0.14.25 \ llama-index-vector-stores-pinecone==0.9.0 \ llama-index-readers-file==0.7.0 \ arxiv==4.0.1 \ setuptools # (Optional) ``` Set your Pinecone and OpenAI API keys as environment variables: ```shell Shell theme={null} export PINECONE_API_KEY="your-pinecone-api-key" # Get from app.pinecone.io export OPENAI_API_KEY="your-openai-api-key" # Get from platform.openai.com/api-keys ``` All code on this page runs on Python 3.12. ### 2. Load the data This guide uses the [canonical HNSW paper](https://arxiv.org/pdf/1603.09320.pdf) by Yuri Malkov (PDF) as the sample dataset. First, download the PDF from arXiv.org and load it into a LlamaIndex loader called [PDF Loader](https://llamahub.ai/l/file-pdf?from=all). This loader is available (along with many more) on [LlamaHub](https://llamahub.ai/), a directory of data loaders. ```Python Python theme={null} import arxiv from pathlib import Path from urllib.request import urlretrieve from llama_index.readers.file import PDFReader # Download paper to local file system (LFS) # `id_list` contains 1 item that matches our PDF's arXiv ID paper = next(arxiv.Client().results(arxiv.Search(id_list=["1603.09320"]))) urlretrieve(paper.pdf_url, "hnsw.pdf") # Instantiate `PDFReader` from LlamaHub loader = PDFReader() # Load HNSW PDF from LFS documents = loader.load_data(file=Path('./hnsw.pdf')) # Preview one of our documents documents[0] ``` ```text Response theme={null} Document(id_='b0e25022-b6ef-4a39-9705-fdde26f7b1ae', embedding=None, metadata={'page_label': '1', 'file_name': 'hnsw.pdf'}, excluded_embed_metadata_keys=[], excluded_llm_metadata_keys=[], relationships={}, metadata_template='{key}: {value}', metadata_separator='\n', text_resource=MediaResource(embeddings=None, data=None, text="IEEE TRANSACTIONS ON JOURNAL NAME, MANUSCRIPT ID 1 \n \nEfficient and robust approximate nearest \nneighbor search using Hierarchical Navigable \nSmall World graphs \nYu. A. Malkov, D. A. Yashunin \nAbstract — We present a new approach for the approximate K -nearest neighbor search based on navigable small world \ngraphs with controllable hierarchy (Hierarchical NSW, ... ``` Each `Document` has a lot of useful information, but depending on which loader you choose, you may have to clean your data. In this case, you need to remove things like remaining `\n` characters and broken, hyphenated words (e.g., `alg o-\nrithms` → `algorithms`). ```Python Python theme={null} # Clean up our Documents' content import re def clean_up_text(content: str) -> str: """ Remove unwanted characters and patterns in text input. :param content: Text input. :return: Cleaned version of original text input. """ # Fix hyphenated words broken by newline content = re.sub(r'(\w+)-\n(\w+)', r'\1\2', content) # Remove specific unwanted patterns and characters unwanted_patterns = [ "\\n", " —", "——————————", "—————————", "—————", r'\\u[\dA-Fa-f]{4}', r'\uf075', r'\uf0b7' ] for pattern in unwanted_patterns: content = re.sub(pattern, "", content) # Fix improperly spaced hyphenated words and normalize whitespace content = re.sub(r'(\w)\s*-\s*(\w)', r'\1-\2', content) content = re.sub(r'\s+', ' ', content) return content # Call function cleaned_docs = [] for d in documents: cleaned_text = clean_up_text(d.text) d.set_content(cleaned_text) cleaned_docs.append(d) # Inspect output cleaned_docs[0].get_content() ``` ```text Response theme={null} "IEEE TRANSACTIONS ON JOURNAL NAME, MANUSCRIPT ID 1 Efficient and robust approximate nearest neighbor search using Hierarchical Navigable Small World graphs Yu. A. Malkov, D. A. Yashunin Abstract — We present a new approach for the approximate K-nearest neighbor search based on navigable small world graphs with controllable hierarchy (Hierarchical NSW, HNSW). The proposed solution is fully graph-based, ..." ``` A file loader from LlamaHub breaks your PDF down into LlamaIndex [Documents](https://developers.llamaindex.ai/python/framework/module_guides/loading/documents_and_nodes/#documents-nodes). Each Document object comes with a [customizable](https://developers.llamaindex.ai/python/framework/module_guides/loading/documents_and_nodes/usage_documents/#metadata) metadata dictionary and a hash ID, among other useful artifacts. ### 3. Transform the data #### Metadata If you look at one of your cleaned Document objects, you'll see that the default values in your metadata dictionary aren't particularly useful. ```Python Python theme={null} cleaned_docs[0].metadata ``` ```text Response theme={null} {'page_label': '1', 'file_name': 'hnsw.pdf'} ``` To make the metadata more helpful, add the authors' names and the paper's title. Whatever metadata you add to the metadata dictionary applies to all [Nodes](https://developers.llamaindex.ai/python/framework/module_guides/loading/documents_and_nodes/#nodes), so keep your additions high-level. > [!NOTE] > > LlamaIndex also provides [advanced customizations](https://developers.llamaindex.ai/python/framework/module_guides/loading/documents_and_nodes/usage_documents/#advanced-metadata-customization) for what metadata the LLM can see vs. the embedding, etc. ```Python Python theme={null} # Iterate through `documents` and add our new key:value pairs metadata_additions = {"authors": ["Yu. A. Malkov", "D. A. Yashunin"], "title": "Efficient and robust approximate nearest neighbor search using Hierarchical Navigable Small World graphs"} # Update dict in place for cd in cleaned_docs: cd.metadata.update(metadata_additions) # Let's confirm everything worked: cleaned_docs[0].metadata ``` ```text Response theme={null} {'page_label': '1', 'file_name': 'hnsw.pdf', 'authors': ['Yu. A. Malkov', 'D. A. Yashunin'], 'title': 'Efficient and robust approximate nearest neighbor search using Hierarchical Navigable Small World graphs'} ``` #### Ingestion pipeline To turn your data into indexable vectors and put them into Pinecone, create what's called an [Ingestion Pipeline](https://developers.llamaindex.ai/python/framework/module_guides/loading/ingestion_pipeline/). An Ingestion Pipeline takes your list of Documents, parses them into Nodes (or "[chunks](https://www.pinecone.io/learn/chunking-strategies/)" in non-LlamaIndex contexts), vectorizes each Node's content, and upserts them into Pinecone. In the following pipeline, you'll use LlamaIndex's [SemanticSplitterNodeParser](https://developers.llamaindex.ai/python/framework/module_guides/loading/node_parsers/modules/#semanticsplitternodeparser), which uses OpenAI's [text-embedding-3-small model](https://platform.openai.com/docs/models/text-embedding-3-small) to split Documents into semantically coherent Nodes. This step uses the OpenAI API key you set as an environment variable [earlier](#set-up-the-environment). ```Python Python theme={null} import os from llama_index.core.node_parser import SemanticSplitterNodeParser from llama_index.embeddings.openai import OpenAIEmbedding from llama_index.core.ingestion import IngestionPipeline # This will be the model we use both for Node parsing and for vectorization embed_model = OpenAIEmbedding( model="text-embedding-3-small", api_key=os.environ["OPENAI_API_KEY"], ) # Define the initial pipeline pipeline = IngestionPipeline( transformations=[ SemanticSplitterNodeParser( buffer_size=1, breakpoint_percentile_threshold=95, embed_model=embed_model, ), embed_model, ], ) ``` Don't run this pipeline yet. You'll modify it in the next section. ### 4. Upsert the data The Ingestion Pipeline you defined still needs a vector store to upsert your transformed data into. LlamaIndex lets you declare a [VectorStore](https://developers.llamaindex.ai/python/examples/vector_stores/pineconeindexdemo/) and add it directly to the pipeline for ingestion. The following code does this with Pinecone. This step uses the Pinecone API key you set as an environment variable [earlier](#set-up-the-environment). ```Python Python theme={null} from pinecone.grpc import PineconeGRPC from pinecone import ServerlessSpec from llama_index.vector_stores.pinecone import PineconeVectorStore # Initialize connection to Pinecone pc = PineconeGRPC(api_key=os.environ["PINECONE_API_KEY"]) index_name = "llama-integration-example" # Create your index if it doesn't exist if not pc.has_index(index_name): pc.create_index( name=index_name, dimension=1536, metric="cosine", spec=ServerlessSpec(cloud="aws", region="us-east-1"), ) # Initialize your index pinecone_index = pc.Index(index_name) # Initialize VectorStore vector_store = PineconeVectorStore(pinecone_index=pinecone_index) ``` Now that your `PineconeVectorStore` is initialized, add it to your `pipeline` and run it. ```Python Python theme={null} # Our pipeline with the addition of our PineconeVectorStore pipeline = IngestionPipeline( transformations=[ SemanticSplitterNodeParser( buffer_size=1, breakpoint_percentile_threshold=95, embed_model=embed_model, ), embed_model, ], vector_store=vector_store, # Our new addition ) # Now we run our pipeline! pipeline.run(documents=cleaned_docs) ``` Confirm that your index is up and running with a Pinecone-native method like `.describe_index_stats()`: ```Python Python theme={null} pinecone_index.describe_index_stats() ``` ```text Response theme={null} DescribeIndexStatsResponse(dimension=1536, total_vector_count=46, metric='cosine', namespaces=1) ``` Your index now has vectors in it. Because it has 46 vectors, you can infer that your `SemanticSplitterNodeParser` split your list of Documents into 46 Nodes. ### 5. Query the data To fetch search results from Pinecone itself, you need to create a [VectorStoreIndex](https://developers.llamaindex.ai/python/framework/module_guides/indexing/vector_store_index/) object and a [VectorIndexRetriever](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/indices/vector_store/retrievers/retriever.py) object. You can then pass natural language queries to your Pinecone index and receive results. ```Python Python theme={null} from llama_index.core import VectorStoreIndex from llama_index.core.retrievers import VectorIndexRetriever # Instantiate VectorStoreIndex object from your vector_store object vector_index = VectorStoreIndex.from_vector_store( vector_store=vector_store, embed_model=embed_model, ) # Grab 5 search results retriever = VectorIndexRetriever(index=vector_index, similarity_top_k=5) # Query vector DB answer = retriever.retrieve('How does logarithmic complexity affect graph construction?') # Inspect results print([i.get_content() for i in answer]) ``` ```text Response theme={null} ['AUTHOR ET AL.: TITLE 7 be auto-configured by using sample data. The construction process can be easily and efficiently parallelized ...', 'AUTHOR ET AL.: TITLE 3 from a low degree node and traverses the graph simultaneously increasing the node’s degree ...', 'the number of distance calculations). Links to the closest neighbors in a k-NN graph serve as a simple approximation of the Delaunay graph ...', 'Simulations show that at least for low dimensional data (Fig. 11, d=4) the dependence of the required ef parameter ...', '4 IEEE TRANSACTIONS ON JOURNAL NAME, MANUSCRIPT ID NSW approach thus can utilize the same methods for making the distributed approximate search/overlay structures ...'] ``` These search results can now be plugged into any downstream task you want. One of the most common ways to use these search results is as additional context to augment a query sent to an LLM. This workflow is commonly called a [RAG application](https://www.pinecone.io/learn/retrieval-augmented-generation/). ### 6. Build a RAG app with the data You could create a [Query Engine](https://developers.llamaindex.ai/python/framework/module_guides/deploying/query_engine/usage_pattern/#usage-pattern) out of your `vector_index` object by calling `vector_index.as_query_engine().query('some query')`, but then you wouldn't be able to specify the number of Pinecone search results you'd like to use as context. To control how many search results your RAG app uses from your Pinecone index, create your Query Engine with the [RetrieverQueryEngine](https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/query_engine/retriever_query_engine.py) class instead. This class lets you pass in the `retriever` you created earlier, which you configured to retrieve the top 5 search results. ```Python Python theme={null} from llama_index.core import Settings from llama_index.core.query_engine import RetrieverQueryEngine from llama_index.llms.openai import OpenAI # Set the LLM that generates answers (and evaluates them later) Settings.llm = OpenAI(model="gpt-4o-mini") # Pass in your retriever from above, which is configured to return the top 5 results query_engine = RetrieverQueryEngine(retriever=retriever) # Now you query: llm_query = query_engine.query('How does logarithmic complexity affect graph construction?') llm_query.response ``` ```text Response theme={null} 'Logarithmic complexity in graph construction allows for efficient scaling as the dataset size increases. Specifically, it ensures that the time required to construct the graph grows at a manageable rate, proportional to the logarithm of the number of elements rather than linearly. This means that even as the dataset expands, the construction process remains feasible and does not become prohibitively time-consuming. The construction complexity is influenced by parameters that control the number of connections and layers, allowing for a balance between speed and the quality of the resulting graph. Consequently, this logarithmic scaling facilitates the handling of large datasets while maintaining performance.' ``` You can also inspect the context (Nodes) that informed your LLM's answer with the `.source_nodes` attribute. The following example inspects the first Node: ```Python Python theme={null} llm_query.source_nodes[0].get_content() ``` ```text Response theme={null} 'AUTHOR ET AL.: TITLE 7 be auto-configured by using sample data. The construction process can be easily and efficiently parallelized with only few synchronization points (as demonstrated in Fig. 9) and no measurable effect on index quality. Construction speed/index quality tradeoff is controlled via ...' ``` ### 7. Evaluate the data Now that you've made a RAG app and queried your LLM, evaluate its response. With LlamaIndex, there are [many ways](https://developers.llamaindex.ai/python/framework/module_guides/evaluating/usage_pattern/) to evaluate the results your RAG app generates. A good first step is to confirm (or deny) that your LLM's responses are relevant, given the context retrieved from your Pinecone index. To do this, you can use LlamaIndex's [RelevancyEvaluator](https://developers.llamaindex.ai/python/examples/evaluation/relevancy_eval/#relevancy-evaluator) class. This type of evaluation doesn't need [ground truth data](https://dtunkelang.medium.com/evaluating-search-using-human-judgement-fbb2eeba37d9) (i.e., labeled datasets to compare answers with). ```Python Python theme={null} from llama_index.core.evaluation import RelevancyEvaluator # (Need to avoid peripheral asyncio issues) import nest_asyncio nest_asyncio.apply() # Define evaluator evaluator = RelevancyEvaluator() # Issue query llm_response = query_engine.query( "How does logarithmic complexity affect graph construction?" ) # Grab context used in answer query & make it pretty llm_response_source_nodes = [i.get_content() for i in llm_response.source_nodes] # Take your previous question and pass in the response you got above eval_result = evaluator.evaluate_response(query="How does logarithmic complexity affect graph construction?", response=llm_response) # Print response print(f'\nGiven the {len(llm_response_source_nodes)} chunks of content (below), is your ' f'LLM\'s response relevant? {eval_result.passing}\n' f'\n ----Contexts----- \n' f'\n{llm_response_source_nodes}') ``` ```text Response theme={null} Given the 5 chunks of content (below), is your LLM's response relevant? True ----Contexts----- ['AUTHOR ET AL.: TITLE 7 be auto-configured by using sample data. The construction process can be easily and efficiently parallelized with only few synchronization points (as demonstrated in Fig...'] ``` Your evaluator's result has various attributes you can inspect to see what's going on behind the scenes. To get a quick binary True/False signal as to whether your LLM is producing relevant results given your context, inspect the `.passing` attribute. Next, send an out-of-scope query through your RAG app. Issue a random query you know your RAG app can't answer, given what's in your index: ```Python Python theme={null} query = "Why did the chicken cross the road?" response = query_engine.query(query) print(response.response) ``` ```text Response theme={null} To get to the other side. ``` Then evaluate the response. The evaluator returns `False`, because the answer doesn't come from the retrieved context: ```Python Python theme={null} eval_result = evaluator.evaluate_response(query=query, response=response) print(str(eval_result.passing)) ``` ```text Response theme={null} False ``` As expected, when you send an out-of-scope question through your RAG pipeline, your evaluator says the LLM's answer isn't relevant to the retrieved context. ### 8. Clean up When you're finished with the index, delete it. ```Python Python theme={null} pc.delete_index(name=index_name) ``` ### Summary This guide covered how to build semantic search and RAG applications with LlamaIndex and Pinecone, and LlamaIndex has many more features. [Explore more](https://developers.llamaindex.ai/python/framework/) on your own and [let us know how it goes](https://discord.gg/tJ8V62S3sH). # Matillion Source: https://docs.pinecone.io/integrations/matillion Use Matillion Data Productivity Cloud to chunk, embed, and upsert data into Pinecone with low-code AI pipelines for RAG, ETL, and GenAI apps. [Matillion Data Productivity Cloud](https://www.matillion.com/) is a platform for building and managing graphical, low-code data pipelines in one place. Data teams use it to bring structured, semi-structured, and unstructured data into analytics and to build AI pipelines. You can use Matillion Data Productivity Cloud with Pinecone for retrieval-augmented generation (RAG) use cases without writing code. Matillion supports 150+ pre-built data source connectors, and you can build custom connectors to any REST API source system. You can use them to chunk unstructured datasets, create embeddings, and upsert to Pinecone. Matillion's graphical AI Prompt Components integrate with large language models (LLMs) running in OpenAI, Amazon Bedrock, Azure OpenAI, and Snowpark Container Services. They provide no-code lookup of external knowledge stored in Pinecone, so data engineers can enrich generative AI answers with contextual, proprietary data. [Get started](https://docs.matillion.com/data-productivity-cloud/designer/docs/pinecone-vector-upsert/) ## Resources * Video: [Use RAG with a Pinecone Vector database on the Data Productivity Cloud](https://www.youtube.com/watch?v=BsH7WlJdoFs) * Video: [How to upsert to your Pinecone Vector database](https://www.youtube.com/watch?v=l9qt-EzLkgY) * [Unlock the power of AI in Data Engineering](https://www.matillion.com/blog/matillion-new-ai-capabilities-for-data-engineering) # Microsoft Marketplace Source: https://docs.pinecone.io/integrations/microsoft-marketplace Buy and manage Pinecone through Microsoft Marketplace with pay-as-you-go billing, centralized SaaS procurement, and simplified Azure licensing. Access Pinecone through its Microsoft Marketplace listing. Microsoft Marketplace lets you manage Pinecone and other third-party software from a centralized location, and simplifies software licensing and procurement with flexible pricing options and multiple deployment methods. You can set up pay-as-you-go billing for a Pinecone organization through Microsoft Marketplace. [Get started](https://marketplace.microsoft.com/product/saas/pineconesystemsinc1688761585469.pineconesaas) # n8n Source: https://docs.pinecone.io/integrations/n8n Use the Pinecone Vector Store and Pinecone Assistant nodes in n8n to build RAG pipelines, semantic search, and no-code AI automations with 400+ apps. n8n is a workflow automation platform that combines AI capabilities with business process automation. Add the Pinecone Vector Store or Pinecone Assistant nodes to your automation pipelines to build AI workflows with vector search and retrieval. Released under a fair-code license, n8n can be self-hosted and is supported by a community of developers and builders. Use the visual builder for simple workflows and add custom JavaScript or Python where you need more control. ## Two ways to use Pinecone in n8n Use the Pinecone Vector Store node for full control over RAG pipelines. It gives you direct access to Pinecone Database, so you can choose embedding models, customize chunking, and control search (semantic, lexical, or hybrid). It works well for wiring up custom nodes for each step and tuning everything to a specific use case. See the [Pinecone Vector Store integration on n8n](https://n8n.io/integrations/pinecone-vector-store/) for node docs, supported modes (insert, retrieve, update), and workflow templates. Use the Pinecone Assistant node for managed RAG with minimal setup. Upload files (PDF, DOCX, TXT, JSON, Markdown), connect any data source, and get knowledge retrieval that's ready for production. One node handles chunking, embedding, vector search, query planning, and reranking. It works well for AI workflows that need trusted, grounded context without configuring pipelines. See the [Pinecone Assistant integration on n8n](https://n8n.io/integrations/pinecone-assistant/) for installation and workflow templates. The following quickstart uses the **Pinecone Assistant** node. [View Assistant Quickstart](/guides/assistant/quickstart/n8n-quickstart) ## Getting started (Pinecone Assistant) Follow the [complete Pinecone Assistant quickstart guide](/guides/assistant/quickstart/n8n-quickstart) to do the following: * Install the Pinecone Assistant node in n8n * Get your API keys * Create your first assistant * Import a ready-to-use workflow template * Start chatting with your documents You can also use the [n8n skill](/integrations/ai-coding-tools) to build n8n workflows in AI coding tools like Claude Code and Cursor. # Nexla Source: https://docs.pinecone.io/integrations/nexla Use Nexla no-code data pipelines to ingest from SharePoint, OneDrive, and 500+ sources into Pinecone for enterprise RAG and vector search apps. Nexla is a data and AI integration platform for building no-code and low-code data pipelines. The Pinecone integration with Nexla lets you ingest data into Pinecone from systems like SharePoint, OneDrive, cloud storage, and data warehouses, plus 500+ other connectors that Nexla supports natively. [Get started](https://docs.nexla.com/tutorials/write-to-vector-db/) [Sign up for Nexla](https://nexla.com/free-trial/) # Integrations overview 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. ## AI coding tools To compare setup across tools, see [AI coding tools](/integrations/ai-coding-tools). > [card] > > Agent SkillsUniversal Pinecone skills library for GitHub Copilot and other agentic IDEs. > > [Open](/integrations/agent-skills) > [card] > > Claude Code pluginOfficial Pinecone plugin for Claude Code with skills, MCP tools, and slash commands. > > [Open](/integrations/claude-code) > [card] > > Codex pluginOfficial Pinecone plugin for Codex with skills and MCP tools. > > [Open](/integrations/codex) > [card] > > Cursor pluginOfficial Pinecone plugin for Cursor with skills, MCP tools, and slash commands. > > [Open](/integrations/cursor) ## Data sources > [card] > > ![](https://mintcdn.com/pinecone/-4J8tNwjqgTl1iBy/images/integrations/airbyte.png?fit=max\&auto=format\&n=-4J8tNwjqgTl1iBy\&q=85\&s=82f0511cc3ac3bc9c24c191eca370667) > > AirbyteIntegrate, transform, and load data into Pinecone from hundreds of systems, including databases, data warehouses, and SaaS products. > > [Open](/integrations/airbyte) > [card] > > ![](https://mintcdn.com/pinecone/-4J8tNwjqgTl1iBy/images/integrations/apify.png?fit=max\&auto=format\&n=-4J8tNwjqgTl1iBy\&q=85\&s=fade046ffd954bfde6c58cbf9bfc7d88) > > ApifyIntegrate results from web scrapers or crawlers into Pinecone to support RAG or semantic search over web content. > > [Open](/integrations/apify) > [card] > > ![](https://mintcdn.com/pinecone/-4J8tNwjqgTl1iBy/images/integrations/aryn.png?fit=max\&auto=format\&n=-4J8tNwjqgTl1iBy\&q=85\&s=975621c4bb7044420faf5c7382c3bc59) > > ArynProcess complex, unstructured documents with an ETL system built for RAG and generative AI applications. > > [Open](/integrations/aryn) > [card] > > ![](https://mintcdn.com/pinecone/-4J8tNwjqgTl1iBy/images/integrations/box.png?fit=max\&auto=format\&n=-4J8tNwjqgTl1iBy\&q=85\&s=732014323042c3228d027c75def2911a) > > BoxConnect a Box account to Pinecone Database. > > [Open](/integrations/box) > [card] > > ![](https://mintcdn.com/pinecone/-4J8tNwjqgTl1iBy/images/integrations/confluent.png?fit=max\&auto=format\&n=-4J8tNwjqgTl1iBy\&q=85\&s=cb141bceada6b4aff7889f5b59c5deed) > > ConfluentStream content from Confluent Cloud into a Pinecone index with the Pinecone Sink Connector for Kafka Connect. > > [Open](/integrations/confluent) > [card] > > ![](https://mintcdn.com/pinecone/nDdCh80h-wik111G/images/integrations/databricks.svg?fit=max\&auto=format\&n=nDdCh80h-wik111G\&q=85\&s=b9723cd60072052c3d56c4f37f730d55) > > DatabricksCombine the Databricks analytics platform with Pinecone for large-scale data processing. > > [Open](/integrations/databricks) > [card] > > ![](https://mintcdn.com/pinecone/-4J8tNwjqgTl1iBy/images/integrations/estuary.png?fit=max\&auto=format\&n=-4J8tNwjqgTl1iBy\&q=85\&s=6b8e1be3fbaac36951046f83506ec608) > > EstuaryMove data from hundreds of systems into Pinecone and keep it up to date. > > [Open](/integrations/estuary) > [card] > > ![](https://mintcdn.com/pinecone/nDdCh80h-wik111G/images/integrations/fleak.svg?fit=max\&auto=format\&n=nDdCh80h-wik111G\&q=85\&s=edf87ed1c4a9f0976327d04cd002f215) > > FleakBuild, deploy, and manage workflows with a low-code platform for AI-assisted ML and LLM transformations. > > [Open](/integrations/fleak) > [card] > > ![](https://mintcdn.com/pinecone/-4J8tNwjqgTl1iBy/images/integrations/flowise.png?fit=max\&auto=format\&n=-4J8tNwjqgTl1iBy\&q=85\&s=d3cfc5e92201ebf64cd6f4ce383062ba) > > FlowiseAIBuild customized LLM apps with an open-source, low-code tool for orchestration flows and AI agents. > > [Open](/integrations/flowise) > [card] > > ![](https://mintcdn.com/pinecone/nDdCh80h-wik111G/images/integrations/gathr.svg?fit=max\&auto=format\&n=nDdCh80h-wik111G\&q=85\&s=f5df8f0f4387f957bad63b1f10d133d4) > > GathrBuild and operationalize data and AI-driven solutions at scale. > > [Open](/integrations/gathr) > [card] > > ![](https://mintcdn.com/pinecone/-4J8tNwjqgTl1iBy/images/integrations/matillion.png?fit=max\&auto=format\&n=-4J8tNwjqgTl1iBy\&q=85\&s=1dca8685dd07ab23626c88b0f26799ec) > > MatillionCreate and maintain data pipelines, build custom connectors for any source, and choose between AI and high-code options. > > [Open](/integrations/matillion) > [card] > > ![](https://mintcdn.com/pinecone/-4J8tNwjqgTl1iBy/images/integrations/nexla.png?fit=max\&auto=format\&n=-4J8tNwjqgTl1iBy\&q=85\&s=64b0f621cda6fa3c0d739c281859ef97) > > NexlaIngest data from 500+ connectors with Nexla's low-code and no-code AI integration platform. > > [Open](/integrations/nexla) > [card] > > ![](https://mintcdn.com/pinecone/HsZKO51bNmpAasdT/images/integrations/redpanda.svg?fit=max\&auto=format\&n=HsZKO51bNmpAasdT\&q=85\&s=cf30e82abe1194acfe5a47b91b9e8068) > > RedpandaConnect existing data sources to Pinecone with a Kafka-compatible streaming data platform built for data-intensive applications. > > [Open](/integrations/redpanda) > [card] > > ![](https://mintcdn.com/pinecone/-4J8tNwjqgTl1iBy/images/integrations/snowflake.png?fit=max\&auto=format\&n=-4J8tNwjqgTl1iBy\&q=85\&s=70e845761641a778eec1747ad0d4f921) > > Snowflake OpenflowUpsert, query, and delete vectors in a Pinecone index from Openflow data pipelines. > > [Open](/integrations/snowflake-openflow) > [card] > > ![](https://mintcdn.com/pinecone/HsZKO51bNmpAasdT/images/integrations/streamnative.svg?fit=max\&auto=format\&n=HsZKO51bNmpAasdT\&q=85\&s=d75431c33ac80e6b6549df33577159a0) > > StreamNativeStream data into Pinecone with StreamNative's messaging and event streaming platform. > > [Open](/integrations/streamnative) > [card] > > ![](https://mintcdn.com/pinecone/r0TaYXrfSrAYZYUj/images/integrations/unstructured.png?fit=max\&auto=format\&n=r0TaYXrfSrAYZYUj\&q=85\&s=2ed3cf2fb6277f97ff6811683d98bf6c) > > UnstructuredLoad data into Pinecone with a single click. > > [Open](/integrations/unstructured) ## Frameworks > [card] > > ![](https://mintcdn.com/pinecone/YhGPIXwx2i0D3QjI/images/integrations/ai-engine.png?fit=max\&auto=format\&n=YhGPIXwx2i0D3QjI\&q=85\&s=17778f9229c5046988b3ff604c7c6a81) > > AI EngineCreate chatbots, generate content, build AI forms, and automate tasks from your WordPress dashboard. > > [Open](/integrations/ai-engine) > [card] > > Amazon BedrockIntegrate your enterprise data into Amazon Bedrock, using Pinecone to build GenAI applications. > > [Open](/integrations/amazon-bedrock) > [card] > > Amazon SageMakerIntegrate machine learning models with a fully managed service for deployment and scaling. > > [Open](/integrations/amazon-sagemaker) > [card] > > ![](https://mintcdn.com/pinecone/-4J8tNwjqgTl1iBy/images/integrations/cloudera.png?fit=max\&auto=format\&n=-4J8tNwjqgTl1iBy\&q=85\&s=f0096b3df1cb4c19af1afeedf355874c) > > Cloudera AIBuild vector embedding, RAG, and semantic search applications at scale with Cloudera AI. > > [Open](/integrations/cloudera) > [card] > > ![](https://mintcdn.com/pinecone/-4J8tNwjqgTl1iBy/images/integrations/context-data.png?fit=max\&auto=format\&n=-4J8tNwjqgTl1iBy\&q=85\&s=af300f1a6fa4ddc347d7fe6f56015e99) > > Context DataCreate end-to-end data flows that connect data sources to Pinecone. > > [Open](/integrations/context-data) > [card] > > ![](https://mintcdn.com/pinecone/-4J8tNwjqgTl1iBy/images/integrations/genkit.png?fit=max\&auto=format\&n=-4J8tNwjqgTl1iBy\&q=85\&s=eac4e66270a48feb93e1f4c2e4596764) > > GenkitBuild AI-powered applications and agents with Genkit. > > [Open](/integrations/genkit) > [card] > > ![](https://mintcdn.com/pinecone/-4J8tNwjqgTl1iBy/images/integrations/haystack.png?fit=max\&auto=format\&n=-4J8tNwjqgTl1iBy\&q=85\&s=56e03431f80e0f1bb2b70fea1a3258c7) > > HaystackImplement an end-to-end search pipeline for efficient retrieval and question answering over large datasets. > > [Open](/integrations/haystack) > [card] > > ![](https://mintcdn.com/pinecone/-4J8tNwjqgTl1iBy/images/integrations/instill.png?fit=max\&auto=format\&n=-4J8tNwjqgTl1iBy\&q=85\&s=777fcd742c95c16aa04410940cdf61ea) > > Instill AIBuild AI applications with a low-code, full-stack tool for data, model, and pipeline orchestration. > > [Open](/integrations/instill) > [card] > > ![](https://mintcdn.com/pinecone/-4J8tNwjqgTl1iBy/images/integrations/langchain.png?fit=max\&auto=format\&n=-4J8tNwjqgTl1iBy\&q=85\&s=0bf433738cc115904657a4eecac7964d) > > LangChainBuild LLM applications with LangChain, using Pinecone as the vector store. > > [Open](/integrations/langchain) > [card] > > ![](https://mintcdn.com/pinecone/-4J8tNwjqgTl1iBy/images/integrations/llamaindex.png?fit=max\&auto=format\&n=-4J8tNwjqgTl1iBy\&q=85\&s=1bda5b90e9ad147cc4a90b624ec95058) > > LlamaIndexIndex and retrieve your data with LlamaIndex and Pinecone for semantic search and RAG applications. > > [Open](/integrations/llamaindex) > [card] > > ![n8n](https://mintcdn.com/pinecone/ubu6j8FPdmkONcNQ/images/integrations/n8n.png?fit=max\&auto=format\&n=ubu6j8FPdmkONcNQ\&q=85\&s=7646c5f388ee1cbfcf78a898fad4c22e) > > n8nBuild AI workflows with the Pinecone Assistant or Vector Store node, for managed RAG or full control over your pipeline. > > [Open](/integrations/n8n) > [card] > > ![](https://mintcdn.com/pinecone/N52HKfE3FcUQD3yb/images/integrations/progress-agentic-rag.png?fit=max\&auto=format\&n=N52HKfE3FcUQD3yb\&q=85\&s=41dbbdacab5f28cd3483b6b04acd8e27) > > Progress Agentic RAGStore the index for a knowledge box in Pinecone with this RAG-as-a-Service platform, formerly Nuclia. > > [Open](/integrations/progress-agentic-rag) > [card] > > ![](https://mintcdn.com/pinecone/HsZKO51bNmpAasdT/images/integrations/voltagent.svg?fit=max\&auto=format\&n=HsZKO51bNmpAasdT\&q=85\&s=5218badadc295c9d4373b649d357961e) > > VoltAgentBuild AI agents with retrieval-augmented generation (RAG) in VoltAgent, a TypeScript framework. > > [Open](/integrations/voltagent) ## Infrastructure > [card] > > ![](https://mintcdn.com/pinecone/-4J8tNwjqgTl1iBy/images/integrations/aws.png?fit=max\&auto=format\&n=-4J8tNwjqgTl1iBy\&q=85\&s=450374ce6c2900bc89bb92b94ea6e5e3) > > AWS MarketplaceAccess Pinecone through its AWS Marketplace listing. > > [Open](/integrations/aws-marketplace) > [card] > > ![](https://mintcdn.com/pinecone/-4J8tNwjqgTl1iBy/images/integrations/gcp.png?fit=max\&auto=format\&n=-4J8tNwjqgTl1iBy\&q=85\&s=6d86fdcad91fb4266758cc85ae899b81) > > Google Cloud MarketplaceAccess Pinecone through its Google Cloud Marketplace listing. > > [Open](/integrations/google-cloud-marketplace) > [card] > > ![](https://mintcdn.com/pinecone/-4J8tNwjqgTl1iBy/images/integrations/azure.png?fit=max\&auto=format\&n=-4J8tNwjqgTl1iBy\&q=85\&s=bbcb055c142f796e3bd1769efa5112df) > > Microsoft MarketplaceAccess Pinecone through its Microsoft Marketplace listing. > > [Open](/integrations/microsoft-marketplace) > [card] > > ![](https://mintcdn.com/pinecone/-4J8tNwjqgTl1iBy/images/integrations/pulumi.png?fit=max\&auto=format\&n=-4J8tNwjqgTl1iBy\&q=85\&s=5a02b6d8249d87a490ecdc2f4f0ba166) > > PulumiManage your Pinecone collections and indexes as code in any language that Pulumi supports. > > [Open](/integrations/pulumi) > [card] > > ![](https://mintcdn.com/pinecone/HsZKO51bNmpAasdT/images/integrations/terraform.svg?fit=max\&auto=format\&n=HsZKO51bNmpAasdT\&q=85\&s=9321956188566f573ec52c1abe4728d5) > > TerraformManage Pinecone resources with Terraform configuration files for a consistent workflow. > > [Open](/integrations/terraform) > [card] > > ![](https://mintcdn.com/pinecone/r0TaYXrfSrAYZYUj/images/integrations/vercel.png?fit=max\&auto=format\&n=r0TaYXrfSrAYZYUj\&q=85\&s=b35d6a3bdf590f2f735c40eb6deea684) > > VercelUse Pinecone as the long-term memory for your Vercel AI projects, and scale to billions of data points. > > [Open](/integrations/vercel) > [card] > > ![](https://mintcdn.com/pinecone/vm6y8tUlUErsL7WY/images/integrations/zapier.png?fit=max\&auto=format\&n=vm6y8tUlUErsL7WY\&q=85\&s=dfe9e863e9cb0890f0101860f77b24ff) > > ZapierConnect Pinecone to thousands of apps with Zapier to automate your work without code. > > [Open](/integrations/zapier) ## Models > [card] > > ![](https://mintcdn.com/pinecone/nDdCh80h-wik111G/images/integrations/cohere.svg?fit=max\&auto=format\&n=nDdCh80h-wik111G\&q=85\&s=74614d43d891a267a198ba605a6472f1) > > CohereGenerate text embeddings with Cohere and store them in Pinecone for semantic search. > > [Open](/integrations/cohere) > [card] > > ![](https://mintcdn.com/pinecone/HsZKO51bNmpAasdT/images/integrations/voyage.svg?fit=max\&auto=format\&n=HsZKO51bNmpAasdT\&q=85\&s=6e8c21b8e8d225f2ec75a66fe78efe52) > > Voyage AIGenerate embeddings with Voyage AI models for semantic search and RAG. > > [Open](/integrations/voyage) > [card] > > ![](https://mintcdn.com/pinecone/nDdCh80h-wik111G/images/integrations/huggingface.svg?fit=max\&auto=format\&n=nDdCh80h-wik111G\&q=85\&s=369c460287a5f12c406de4fb2eb4c85f) > > Hugging FaceDeploy machine learning models on Hugging Face Inference Endpoints and use them to create embeddings for Pinecone. > > [Open](/integrations/hugging-face-inference-endpoints) > [card] > > ![](https://mintcdn.com/pinecone/-4J8tNwjqgTl1iBy/images/integrations/jina.png?fit=max\&auto=format\&n=-4J8tNwjqgTl1iBy\&q=85\&s=b3fb233a5438f771e10cc94061a49188) > > JinaGenerate text embeddings with Jina AI models, fine-tuned for domain- and language-specific use cases. > > [Open](/integrations/jina) > [card] > > OpenAIUse OpenAI models to generate embeddings and responses, and store the embeddings in Pinecone. > > [Open](/integrations/openai) > [card] > > ![](https://mintcdn.com/pinecone/r0TaYXrfSrAYZYUj/images/integrations/twelve-labs.png?fit=max\&auto=format\&n=r0TaYXrfSrAYZYUj\&q=85\&s=cbfeeb44f58ddc2fb4c4aa9e0dacbe84) > > Twelve LabsCreate multimodal embeddings from video with Twelve Labs and store them in Pinecone. > > [Open](/integrations/twelve-labs) ## Observability > [card] > > ![](https://mintcdn.com/pinecone/nDdCh80h-wik111G/images/integrations/datadog.svg?fit=max\&auto=format\&n=nDdCh80h-wik111G\&q=85\&s=482a717ea863cc80456922d825052aaa) > > DatadogMonitor your Pinecone usage and performance with Datadog dashboards and alerts. > > [Open](/integrations/datadog) > [card] > > ![](https://mintcdn.com/pinecone/-4J8tNwjqgTl1iBy/images/integrations/honeyhive.png?fit=max\&auto=format\&n=-4J8tNwjqgTl1iBy\&q=85\&s=f98500a3e97abca67649d778ad1112b0) > > HoneyHiveVisualize execution traces and spans from your Pinecone calls. > > [Open](/integrations/honeyhive) > [card] > > ![](https://mintcdn.com/pinecone/-4J8tNwjqgTl1iBy/images/integrations/new-relic.png?fit=max\&auto=format\&n=-4J8tNwjqgTl1iBy\&q=85\&s=ff34e204c22601c7ec5d258116b89dca) > > New RelicMonitor your Pinecone application with New Relic for performance analysis. > > [Open](/integrations/new-relic) > [card] > > ![](https://mintcdn.com/pinecone/r0TaYXrfSrAYZYUj/images/integrations/traceloop.png?fit=max\&auto=format\&n=r0TaYXrfSrAYZYUj\&q=85\&s=3d27ca8106c56a2408b84d8d9ddf2e9d) > > TraceloopProduce traces and metrics that can be viewed in any OpenTelemetry-based platform. > > [Open](/integrations/traceloop) > [card] > > ![](https://mintcdn.com/pinecone/r0TaYXrfSrAYZYUj/images/integrations/trulens.png?fit=max\&auto=format\&n=r0TaYXrfSrAYZYUj\&q=85\&s=bc486fd4b07de8df11fd316a713077ef) > > TruLensEvaluate and track RAG applications built on Pinecone with TruLens. > > [Open](/integrations/trulens) # Progress Agentic RAG Source: https://docs.pinecone.io/integrations/progress-agentic-rag Store the index for a Progress Agentic RAG knowledge box in Pinecone. Progress Agentic RAG, formerly Nuclia, provides RAG-as-a-Service over your documents. [Progress Agentic RAG](https://www.progress.com/agentic-rag), formerly Nuclia, is a RAG-as-a-Service platform. It indexes files and documents from internal and external sources so you can use them with large language models (LLMs). You can customize the RAG pipeline for your use case, including the retrieval and chunking strategies and the embedding model. When you create a knowledge box, you can choose to store its index in Pinecone. This is especially useful for large datasets where full-text search isn't key in the retrieval phase. [Get started](https://docs.rag.progress.cloud/docs/develop/js-sdk/interfaces/ExternalIndexProvider) # Pulumi Source: https://docs.pinecone.io/integrations/pulumi Provision Pinecone indexes and collections as code with Pulumi in Python, TypeScript, Go, or C#. Pulumi is an infrastructure-as-code platform that lets you use familiar programming languages and tools to build, deploy, and manage cloud infrastructure. Pulumi is free and open source, and optionally pairs with Pulumi Cloud to help you manage infrastructure. The Pulumi Pinecone Provider lets you manage your Pinecone collections and indexes in any language that Pulumi supports. [Get started](https://www.pulumi.com/registry/packages/pinecone/) # Redpanda Source: https://docs.pinecone.io/integrations/redpanda Stream events into Pinecone with Redpanda Connect's declarative YAML pipelines for real-time vector ingestion, at-least-once delivery, and RAG ETL. Redpanda Connect is a declarative data streaming service that handles data engineering tasks with chained, stateless processing steps. The Pinecone connector for Redpanda writes data from many existing data sources to Pinecone, configured in a few lines of YAML. Redpanda Connect implements transaction-based resiliency with back pressure, so when connecting to at-least-once sources and sinks, it guarantees at-least-once delivery without persisting messages during transit. Redpanda Connect comes with a wide range of connectors and is data agnostic, so you can add it to your existing infrastructure. Its functionality overlaps with integration frameworks, log aggregators, and ETL workflow engines, so you can use it to complement these tools or as a simpler alternative. [Get started](https://docs.redpanda.com/redpanda-connect/components/outputs/pinecone/) # Snowflake Openflow Source: https://docs.pinecone.io/integrations/snowflake-openflow Use the Pinecone processors in Snowflake Openflow to upsert, query, and delete vectors in a Pinecone index as part of a data pipeline. [Snowflake Openflow](https://docs.snowflake.com/en/user-guide/data-integration/openflow/about) is a data integration service built on Apache NiFi. Datavolo previously offered this integration. Snowflake acquired Datavolo in 2024. Openflow includes processors that work with a Pinecone index: * `UpsertPinecone` publishes vectors, including metadata and optionally text, to a Pinecone index. * `QueryPinecone` queries Pinecone for vectors that are similar to an input vector, or retrieves a vector by ID. * `DeletePinecone` deletes vectors from a Pinecone index. [Get started](https://docs.snowflake.com/en/user-guide/data-integration/openflow/processors/upsertpinecone) # StreamNative Source: https://docs.pinecone.io/integrations/streamnative Use the StreamNative Pinecone sink connector to write messages from Apache Pulsar topics to a Pinecone index for real-time vector ingestion. [StreamNative](https://streamnative.io) provides StreamNative Cloud, a messaging and event streaming platform that offers Apache Pulsar as a Service. The Pinecone integration with StreamNative connects a Pulsar topic to Pinecone. The sink connector takes in messages and, if they're in the correct format, writes them to a Pinecone index. StreamNative was founded by the original developers of Apache Pulsar and Apache BookKeeper. It also supports on-premises Pulsar deployments with commercial support, and offers Kafka compatibility for integrating with existing Kafka-based systems. [Get started](https://docs.streamnative.io/hub/connector-pinecone-sink-v3.3#pinecone-sink-connector) # Terraform Source: https://docs.pinecone.io/integrations/terraform Manage Pinecone indexes, collections, projects, API keys, and access with the Terraform provider for repeatable infrastructure-as-code and DevOps workflows. Terraform is an infrastructure-as-code tool that lets you create, update, and version infrastructure by defining resources in configuration files. This gives you a repeatable workflow for provisioning and managing your infrastructure. This page describes how to use the [Terraform Provider for Pinecone](https://registry.terraform.io/providers/pinecone-io/pinecone/latest/docs) to manage Pinecone indexes, collections, projects, API keys, service accounts, role bindings, invites, and users. It covers provider v5.1.1, which uses Pinecone API version `2026-07`. ## Requirements Ensure you have the following: * [Terraform](https://developer.hashicorp.com/terraform) >= v1.4.6 * A [Pinecone API key](https://app.pinecone.io/organizations/-/keys) for managing indexes and collections * A [Pinecone service account](https://app.pinecone.io/organizations/-/settings/access/service-accounts) for managing projects, API keys, service accounts, role bindings, invites, and users > [!NOTE] > > [Go](https://go.dev/doc/install) >= v1.26 is required only if you build the provider from source. You don't need Go to install the provider from the Terraform Registry. ## Install the provider 1. Configure the Pinecone provider in your Terraform configuration file: ```hcl Terraform theme={null} terraform { required_providers { pinecone = { source = "pinecone-io/pinecone" version = "~> 5.1" } } } ``` 2. Run `terraform init` to install the provider from the [Terraform Registry](https://registry.terraform.io/providers/pinecone-io/pinecone/latest). Alternatively, you can download the latest binary for your target platform from the [GitHub repository](https://github.com/pinecone-io/terraform-provider-pinecone/releases). ### Upgrade from v4 v5 is a major version. Most configurations written for v4 plan with no changes, but a few that v4 accepted are now rejected at plan time, before anything changes: * New [pod-based indexes](#pod-based-indexes) can't be created, and neither can indexes created from a collection. * On a [legacy integrated index](#legacy-integrated-indexes), `embed` can't be added or removed, and `embed.model` and `embed.field_map` can't be changed. * The `spec.serverless.schema` and `spec.byoc.schema` [metadata schema](#move-an-index-to-the-schema-style) is deprecated. New indexes accept it only together with `embed`. * An index can't switch from dedicated [read capacity](#read-capacity) back to on-demand. * `dimension`, `size`, and `vector_count` on `pinecone_collection` are read-only and can't be set. To upgrade, change the version constraint to `~> 5.1`, run `terraform init -upgrade`, then run `terraform plan` and work through any errors. For each error and its fix, see the [version 5 upgrade guide](https://registry.terraform.io/providers/pinecone-io/pinecone/latest/docs/guides/version-5-upgrade). For the full list of changes, see the [v5.0.0](https://github.com/pinecone-io/terraform-provider-pinecone/releases/tag/v5.0.0), [v5.1.0](https://github.com/pinecone-io/terraform-provider-pinecone/releases/tag/v5.1.0), and [v5.1.1](https://github.com/pinecone-io/terraform-provider-pinecone/releases/tag/v5.1.1) release notes. ## Authenticate The provider uses two kinds of credentials, and each resource requires a specific one. The provider needs at least one of them and fails to configure if neither is set. If your configuration manages both indexes and organization-level resources, set both. | Credential | Environment variables | Resources and data sources | | :- | :- | :- | | [API key](/admin/projects/manage-api-keys) | `PINECONE_API_KEY` | `pinecone_index`, `pinecone_collection` | | [Service account](/admin/organizations/manage-service-accounts) | `PINECONE_CLIENT_ID`, `PINECONE_CLIENT_SECRET` | `pinecone_project`, `pinecone_api_key`, `pinecone_service_account`, `pinecone_role_binding`, `pinecone_invite`, `pinecone_user` | Follow these steps to authenticate: 1. Set environment variables for authentication: ```bash theme={null} # For indexes and collections export PINECONE_API_KEY="YOUR_API_KEY" # For projects, API keys, service accounts, role bindings, invites, and users export PINECONE_CLIENT_ID="YOUR_CLIENT_ID" export PINECONE_CLIENT_SECRET="YOUR_CLIENT_SECRET" ``` 2. Append the following to your Terraform configuration file: ```hcl Terraform theme={null} provider "pinecone" {} ``` > [!NOTE] > > You can also set the API key and service account credentials as [input variables](https://developer.hashicorp.com/terraform/language/values/variables). ## Manage resources The Terraform Provider for Pinecone provides the following resources: | Resource | Description | Credential | | :- | :- | :- | | [`pinecone_index`](#indexes) | Create, update, and delete indexes. | API key | | [`pinecone_collection`](#collections) | Create and delete collections. | API key | | [`pinecone_project`](#projects) | Create, update, and delete projects. | Service account | | [`pinecone_api_key`](#api-keys) | Create, update, and delete API keys. | Service account | | [`pinecone_service_account`](#service-accounts) | Create, update, and delete service accounts. | Service account | | [`pinecone_role_binding`](#role-bindings) | Grant and revoke roles. | Service account | | [`pinecone_invite`](#invites) | Send and revoke organization invitations. | Service account | | [`pinecone_user`](#users) | Remove existing organization members. | Service account | ### Indexes The `pinecone_index` resource lets you create, update, and delete [indexes](/guides/indexes/index-data-overview). It describes an index in one of two styles: * **The `schema` style**, with `schema` and `deployment`. This is how API version `2026-07` describes indexes, and it's the style to use for new indexes. * **The `spec` style**, with `dimension`, `metric`, `vector_type`, `spec`, and `embed`. This is how earlier versions of the provider described indexes, and it's planned for deprecation. Legacy integrated indexes and existing pod-based indexes still need it. A configuration uses one style or the other. You can't combine `schema` or `deployment` with `dimension`, `metric`, `vector_type`, `spec`, or `embed`. #### Document indexes A `schema` of named fields creates a [document index](/guides/get-started/key-terms#document-index), which you read and write through the Documents API. Each field sets exactly one of `dense_vector`, `sparse_vector`, or `string`. A `string` field stores its text by default, and a field that stores its text is always indexed for [full-text search](/guides/search/full-text-search). A `string` field can also use [integrated embedding](#integrated-embedding). ```hcl Terraform theme={null} resource "pinecone_index" "example_index_documents" { name = "example-index-documents" deployment = { managed = { cloud = "aws" region = "us-east-1" } } schema = { fields = { embedding = { dense_vector = { dimension = 1536, metric = "dotproduct" } } terms = { sparse_vector = {} } body = { string = { full_text_search = { stemming = true, stop_words = true } } } title = { string = { full_text_search = { ngram = { min_gram = 2, max_gram = 4, prefix_only = true } } } } } } deletion_protection = "disabled" tags = { environment = "development" } } ``` You don't need to declare metadata fields. Pinecone indexes them automatically as you upsert documents. `full_text_search` accepts `language`, `stemming`, `stop_words`, and `ngram`. `ngram` can't be combined with `stemming` or `stop_words`. Document indexes can run on managed (serverless) or [BYOC](#byoc-indexes) deployments. #### Integrated embedding With provider v5.1.0 or later, a `string` field can use [integrated embedding](/guides/search/integrated-embedding): Pinecone embeds the field's text with a hosted model when you upsert or update documents, and embeds your query text when you search. Set `embed` for a dense model, `sparse_embed` for a sparse model, or both. `{}` selects the default model: `llama-text-embed-v2` at its default dimension and metric for `embed`, and `pinecone-sparse-english-v0` for `sparse_embed`. ```hcl Terraform theme={null} resource "pinecone_index" "example_index_embedded" { name = "example-index-embedded" deployment = { managed = { cloud = "aws" region = "us-east-1" } } schema = { fields = { # Embedded with a dense model. Its stored text is indexed for full-text search, here with stemming. body = { string = { embed = { model = "llama-text-embed-v2", dimension = 1024 } full_text_search = { stemming = true } } } # Embedded with the default sparse model, then discarded summary = { string = { sparse_embed = {} store_text = false } } } } } ``` Note the following behaviors: * `embed` accepts `model`, `dimension`, `metric`, `read_parameters`, and `write_parameters`. `sparse_embed` accepts the same attributes except `dimension` and `metric`. For available models, see [Models](/models/overview). * The read-only `effective_read_parameters` and `effective_write_parameters` attributes report the parameters the index uses, merged with the model's defaults. * One field can set `full_text_search`, `embed`, and `sparse_embed` together. Set `full_text_search` to configure full-text search on a field that stores its text. * `store_text = false` embeds the text and then discards it. Use it for fields you only search by similarity, or to keep sensitive text out of Pinecone. The field then can't use `full_text_search`, `$match_*` filters, or `include_fields`. * An index has one dense slot and one sparse slot. At most one field can be a `dense_vector` field or set `embed`, and at most one can be a `sparse_vector` field or set `sparse_embed`. #### Vector indexes A schema made only of the reserved fields `_values` (dense) and `_sparse_values` (sparse) creates a [legacy vector index](/guides/legacy/vectors-api/create-a-vector-index), which you read and write through the legacy Vectors API. `_values` always needs both `dimension` and `metric`. ```hcl Terraform theme={null} # Index that stores dense vectors resource "pinecone_index" "example_index" { name = "example-index" deployment = { managed = { cloud = "aws" region = "us-west-2" } } schema = { fields = { _values = { dense_vector = { dimension = 1536, metric = "cosine" } } } } } # Index that stores sparse vectors resource "pinecone_index" "example_index_sparse" { name = "example-index-sparse" deployment = { managed = { cloud = "aws" region = "us-west-2" } } schema = { fields = { _sparse_values = { sparse_vector = {} } } } } ``` #### BYOC indexes To create a [BYOC index](/guides/production/bring-your-own-cloud/create-an-index), set `deployment.byoc.environment` to the environment identifier Pinecone provides for your deployment. The Pinecone API accepts document indexes on BYOC as long as no field uses integrated embedding. With provider v5.1.0 or later, BYOC indexes default to on-demand [read capacity](#read-capacity), like serverless indexes. ```hcl Terraform theme={null} resource "pinecone_index" "example_index_byoc" { name = "example-index-byoc" deployment = { byoc = { environment = "YOUR_BYOC_ENVIRONMENT_ID" } } schema = { fields = { _values = { dense_vector = { dimension = 1536, metric = "cosine" } } } } } ``` > [!NOTE] > > Provider v5.0.0 requires `read_capacity.dedicated` on new BYOC indexes. Upgrade to v5.1.0 or later to create on-demand BYOC indexes. > > Provider v5.1.0 and earlier reject document indexes on BYOC at plan time. Upgrade to v5.1.1 or later to use them. #### Read capacity Serverless and BYOC indexes support configurable read capacity through `read_capacity`. There are two modes: `on_demand`, which is the default, and `dedicated`, which provisions [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview). In the `schema` style, set `read_capacity` at the top level of the resource. ```hcl Terraform theme={null} resource "pinecone_index" "example_index_dedicated" { name = "example-index-dedicated" deployment = { managed = { cloud = "aws" region = "us-east-1" } } schema = { fields = { _values = { dense_vector = { dimension = 1536, metric = "cosine" } } } } read_capacity = { dedicated = { node_type = "b1" replicas = 1 shards = 1 } } } ``` Set `node_type` to `b1` or `t1`. The first time you switch an index to dedicated mode, `node_type`, `replicas`, and `shards` are all required. To select on-demand explicitly, set `read_capacity = { on_demand = {} }`. Creating an index with `read_capacity`, or changing `read_capacity`, waits until the configured replicas and shards are running. If the change fails, the apply fails with the API's error message. If a change to an existing index times out, it keeps going, and the next apply waits for it again. > [!WARNING] > > An index can't switch from dedicated read capacity back to on-demand. The plan fails with `Read capacity can't return to on-demand`. To switch an index back, contact [Pinecone support](https://app.pinecone.io/organizations/-/settings/support/ticket). #### Encryption To encrypt an index with [customer-managed encryption keys (CMEK)](/guides/production/configure-cmek), set `cmek_id` to the ID of your key. `cmek_id` is available only in the `schema` style, and only when you create the index. [BYOC](/guides/production/bring-your-own-cloud) indexes don't support CMEK, and setting `cmek_id` on one fails at apply with `Encryption is not supported for BYOC indexes`. To encrypt BYOC data, use your cloud provider's key management service on the resources in your account. ```hcl Terraform theme={null} resource "pinecone_index" "example_index_cmek" { name = "example-index-cmek" cmek_id = "YOUR_CMEK_KEY_ID" deployment = { managed = { cloud = "aws" region = "us-east-1" } } schema = { fields = { _values = { dense_vector = { dimension = 1536, metric = "cosine" } } } } } ``` #### Update and recreate indexes You can [update](/guides/indexes/manage-indexes) the following attributes of an existing index in place: * `deletion_protection` * `tags` * `read_capacity` * `embed.read_parameters` and `embed.write_parameters` on a [legacy integrated index](#legacy-integrated-indexes) * `spec.pod.replicas` and `spec.pod.pod_type` on an existing [pod-based index](#pod-based-indexes) Changing `name`, `schema`, `deployment`, `cmek_id`, `dimension`, `metric`, `vector_type`, or `spec.serverless.cloud` and `region` replaces the index, which deletes the records it holds. Some changes are rejected at plan time instead of replacing the index. These include removing integrated embedding from a field, changing `embed` on a legacy integrated index, and changing a pod-based index in a way that would need a new one. To recreate an index on purpose, taint it, then apply: ```bash theme={null} terraform taint pinecone_index.example_index terraform apply ``` `terraform apply -replace` doesn't get past these errors, because Terraform still plans the change against the existing index first. Use `terraform taint` instead. #### Move an index to the schema style You can move an existing legacy vector index from the `spec` style to the `schema` style without replacing it. Rewrite the configuration to describe the same index, and the plan shows an in-place update that only changes Terraform state. The API isn't called. ```hcl Terraform theme={null} # Before: the spec style resource "pinecone_index" "example_index" { name = "example-index" dimension = 1536 metric = "cosine" spec = { serverless = { cloud = "aws" region = "us-west-2" } } } # After: the schema style resource "pinecone_index" "example_index" { name = "example-index" deployment = { managed = { cloud = "aws" region = "us-west-2" } } schema = { fields = { _values = { dense_vector = { dimension = 1536, metric = "cosine" } } } } } ``` Each attribute maps as follows: | `spec` style | `schema` style | | :- | :- | | `dimension` and `metric`, on an index that stores dense vectors | `schema.fields._values = { dense_vector = { dimension = ..., metric = ... } }` | | `vector_type = "sparse"` | `schema.fields._sparse_values = { sparse_vector = {} }` | | `spec.serverless.cloud` and `region` | `deployment.managed.cloud` and `region` | | `spec.byoc.environment` | `deployment.byoc.environment` | | `spec.serverless.read_capacity` or `spec.byoc.read_capacity` | `read_capacity` | | `spec.serverless.schema` or `spec.byoc.schema` (deprecated) | Remove it. Pinecone indexes metadata automatically. | | `name`, `deletion_protection`, `tags`, `timeouts` | Unchanged | The dimension, metric, and location must match the existing index, or the plan fails with `The configuration describes a different index`. Set `metric` on `_values` even if the `spec` style left it to its default of `cosine`. If the plan shows a replacement, something besides the style changed, such as `name`. Check the configuration before you apply. > [!WARNING] > > The move is one way. An index in the `schema` style can't move back to the `spec` style. Legacy integrated indexes and pod-based indexes can't move to the `schema` style. #### Legacy integrated indexes Indexes created with the top-level `embed` attribute are legacy integrated indexes. You read and write them through the legacy Records API. They still use the `spec` style, and existing configurations keep working. For new indexes, use [integrated embedding](#integrated-embedding) on a document index instead. ```hcl Terraform theme={null} resource "pinecone_index" "example_index_legacy_integrated" { name = "example-index-legacy-integrated" spec = { serverless = { cloud = "aws" region = "us-west-2" } } embed = { model = "llama-text-embed-v2" field_map = { text = "chunk_text" } } } ``` `embed` is fixed when you create the index. You can't add or remove it, or change `model` or `field_map`, on an existing index. You can update `read_parameters` and `write_parameters` in place. #### Pod-based indexes > [!WARNING] > > Pod-based indexes are legacy. Customers who signed up for a Standard or Enterprise plan on or after August 18, 2025 cannot create them. [Create a serverless index](/guides/indexes/create-an-index) instead. Serverless indexes use on-demand read capacity by default, or [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview) for sustained high query rates and workloads of millions of records or more. API version `2026-07` doesn't support creating [pod-based indexes](/guides/legacy/pod-based-indexes/understanding-pod-based-indexes), so the provider can't create them either, including from a collection with `spec.pod.source_collection`. You can still [import](#import-existing-resources), scale, and delete existing pod-based indexes. ```hcl Terraform theme={null} # An existing pod-based index, brought under management with terraform import resource "pinecone_index" "example_index_pod" { name = "example-index-pod" dimension = 1536 spec = { pod = { environment = "us-west4-gcp" pod_type = "p1.x2" replicas = 2 shards = 1 } } } ``` Changing `replicas` or `pod_type` scales the index in place, and the apply waits until scaling finishes. `pod_type` can only grow within the same pod family, for example from `p1.x1` to `p1.x2`. Changes that would replace a pod-based index, such as to `name`, `dimension`, `metric`, `environment`, or `shards`, fail at plan time. #### Timeouts Index creation, updates, and deletion each time out after 10 minutes by default. Creation waits for the index and any read capacity it configures to be ready. Updates wait for read capacity changes and pod-based scaling to finish. To override the defaults, set a `timeouts` block: ```hcl Terraform theme={null} resource "pinecone_index" "example_index_timeouts" { name = "example-index-timeouts" deployment = { managed = { cloud = "aws" region = "us-east-1" } } schema = { fields = { _values = { dense_vector = { dimension = 1536, metric = "cosine" } } } } timeouts { create = "20m" update = "20m" delete = "15m" } } ``` > [!NOTE] > > If creating an index times out, Terraform marks it tainted and replaces it on the next apply. When you create an index with dedicated read capacity, set `timeouts.create` high enough for the read nodes to be provisioned. ### Collections The `pinecone_collection` resource lets you create and delete [collections](/guides/legacy/pod-based-indexes/understanding-collections). Collections are created from pod-based indexes, which can no longer be created, so set `source` to the name of an existing pod-based index. ```hcl Terraform theme={null} resource "pinecone_collection" "example_collection" { name = "example-collection" source = "YOUR_POD_BASED_INDEX_NAME" } ``` `dimension`, `size`, and `vector_count` are read-only. Collections also accept a `timeouts` block for `create` and `delete`, each with a 10-minute default. ### Projects The `pinecone_project` resource lets you create, update, and delete [projects](/admin/projects/projects-overview). Once `force_encryption_with_cmek` is enabled, it can't be disabled. `max_pods` defaults to `0`, which allows serverless indexes only. > [!WARNING] > > Pod-based indexes are legacy. Customers who signed up for a Standard or Enterprise plan on or after August 18, 2025 cannot create them. [Create a serverless index](/guides/indexes/create-an-index) instead. Serverless indexes use on-demand read capacity by default, or [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview) for sustained high query rates and workloads of millions of records or more. Customers on those plans also can't set `max_pods` for a project. ```hcl Terraform theme={null} # Basic project resource "pinecone_project" "example_project" { name = "example-project" } # Project with CMEK encryption enabled resource "pinecone_project" "example_project_encrypted" { name = "example-project-encrypted" force_encryption_with_cmek = true } # Project with custom max pods resource "pinecone_project" "example_project_custom_pods" { name = "example-project-custom-pods" max_pods = 10 } output "project_organization_id" { description = "The organization the project belongs to" value = pinecone_project.example_project.organization_id } ``` ### API keys The `pinecone_api_key` resource lets you create, update, and delete [API keys](/admin/projects/manage-api-keys). Valid `roles` values are `ProjectEditor`, `ProjectViewer`, `ControlPlaneEditor`, `ControlPlaneViewer`, `DataPlaneEditor`, and `DataPlaneViewer`. `roles` defaults to `["ProjectEditor"]`. > [!NOTE] > > You can update only the name and roles of an API key. `project_id` is required when you create a key. ```hcl Terraform theme={null} # API key with default roles (ProjectEditor) resource "pinecone_api_key" "example_key" { name = "example-key" project_id = "YOUR_PROJECT_ID" } # API key with custom roles resource "pinecone_api_key" "example_key_custom_roles" { name = "example-key-custom-roles" project_id = "YOUR_PROJECT_ID" roles = ["ProjectViewer", "DataPlaneViewer"] } output "api_key_roles" { description = "The roles assigned to the API key" value = pinecone_api_key.example_key.roles } ``` > [!WARNING] > > The generated secret is available as the read-only `key` attribute, which the API returns only once, at creation. Terraform stores it in plaintext in state. Marking it sensitive keeps it out of CLI output and logs, but does not encrypt it in state. Secure your state backend and never commit state to version control. ### Service accounts The `pinecone_service_account` resource lets you create, update, and delete [service accounts](/admin/organizations/manage-service-accounts). A service account authenticates with an OAuth client ID and secret. Grant it roles with a [role binding](#role-bindings). ```hcl Terraform theme={null} resource "pinecone_service_account" "example_service_account" { name = "example-service-account" } resource "pinecone_role_binding" "example_service_account_org_member" { principal_id = pinecone_service_account.example_service_account.id principal_type = "service_account" resource_type = "organization" role = "OrgMember" } # Rotate the client secret by changing rotate_trigger to a new value resource "pinecone_service_account" "example_service_account_rotatable" { name = "example-service-account-rotatable" rotate_trigger = "2026-01-01" } output "example_service_account_client_secret" { value = pinecone_service_account.example_service_account.client_secret sensitive = true } ``` To rotate a client secret, change `rotate_trigger` from one non-empty value to another. Setting it for the first time, or clearing it, establishes a baseline without rotating, so an existing credential is never invalidated unintentionally. > [!WARNING] > > The `client_secret` attribute is returned only once, at creation or rotation, and Terraform stores it in plaintext in state. Marking it sensitive keeps it out of CLI output and logs, but does not encrypt it in state. Secure your state backend and never commit state to version control. ### Role bindings The `pinecone_role_binding` resource lets you grant a role to a principal at organization or project scope. For details on the role model, see [Manage roles and access](/admin/security/manage-rbac). * Set `principal_type` to `user`, `service_account`, or `api_key`, and `principal_id` to that principal's ID. * Set `resource_type` to `organization` or `project`. For project scope, `resource_id` is required and must be the project ID. For organization scope, omit `resource_id`. The binding applies to the caller's organization. * Organization-scoped `role` values are `OrgOwner`, `OrgManager`, `OrgBillingAdmin`, and `OrgMember`. Project-scoped values are `ProjectOwner`, `ProjectManager`, `ProjectMember`, `ProjectEditor`, `ProjectViewer`, `ControlPlaneEditor`, `ControlPlaneViewer`, `DataPlaneEditor`, and `DataPlaneViewer`. ```hcl Terraform theme={null} # Organization-scoped role resource "pinecone_role_binding" "example_org_member" { principal_id = "YOUR_SERVICE_ACCOUNT_ID" principal_type = "service_account" resource_type = "organization" role = "OrgMember" } # Project-scoped role resource "pinecone_role_binding" "example_project_editor" { principal_id = "YOUR_USER_ID" principal_type = "user" resource_type = "project" resource_id = "YOUR_PROJECT_ID" role = "ProjectEditor" } ``` > [!NOTE] > > Role bindings are immutable. Changing any attribute revokes the existing binding and creates a new one. The `pinecone_role_binding` resource doesn't accept `principal_type = "invite"`. Pinecone moves an invite's bindings to the user principal when the invite is accepted, so Terraform can't manage them across that transition. To grant roles to someone who hasn't joined your organization yet, use [`pinecone_invite`](#invites), then manage their roles here with `principal_type = "user"` once they accept. The `pinecone_role_bindings` data source does accept `invite`, so you can still read what a pending invite granted. ### Invites The `pinecone_invite` resource manages an [organization invitation](/admin/organizations/manage-organization-members), not the resulting membership. Creating it sends an invite to the given email with a set of initial roles. Deleting it revokes an invite that's still pending. The `role_bindings` list must include at least one organization-scoped role that grants membership. ```hcl Terraform theme={null} # Invite a user as an organization member resource "pinecone_invite" "example_member" { email = "teammate@example.com" role_bindings = [ { resource_type = "organization" role = "OrgMember" } ] } # Invite a user with both organization membership and a project-scoped role resource "pinecone_invite" "example_project_editor" { email = "contractor@example.com" role_bindings = [ { resource_type = "organization" role = "OrgMember" }, { resource_type = "project" role = "ProjectEditor" resource_id = "YOUR_PROJECT_ID" } ] } ``` The read-only `status` attribute reports `pending`, `expired`, or `processed`. Invites expire 7 days after creation, and the provider doesn't expose a way to change that. Once an invite is accepted, its status is `processed` and Terraform stops acting on it. Destroying an accepted invite is a no-op. > [!WARNING] > > Invites are immutable, so changing `email` or `role_bindings` sends a new invite. Don't change either one after the invite is accepted. The replacement re-invites an address that already belongs to a member, and the operation fails. Manage an existing member's roles with [`pinecone_role_binding`](#role-bindings) instead. > [!NOTE] > > Pinecone doesn't return the roles an invite granted, so `role_bindings` is applied only at creation. Terraform can't detect drift on it or recover it on import. To read the bindings, use the `pinecone_role_bindings` data source with `principal_type = "invite"`. ### Users The `pinecone_user` resource manages an existing [organization member](/admin/organizations/manage-organization-members). You can't create or update users through Terraform. They join your organization by accepting an [invite](#invites). Bring an existing user under management with [`terraform import`](#import-existing-resources). To change a user's roles, use a [role binding](#role-bindings). > [!WARNING] > > Destroying a `pinecone_user` resource removes that person from your organization. A `terraform destroy`, or removing the resource from your configuration, revokes a colleague's access to every project in the organization. ```hcl Terraform theme={null} resource "pinecone_user" "example_user" { id = "YOUR_USER_ID" } ``` The `id` attribute is immutable. To manage a different user, run `terraform state rm` on this resource and import the intended one. ## Read existing resources Data sources let you read resources that Terraform doesn't manage. Most resource types have a singular data source that fetches one object and a plural data source that lists many. | Data source | Required | Optional filters | Credential | | :- | :- | :- | :- | | `pinecone_index` | `name` | — | API key | | `pinecone_indexes` | — | — | API key | | `pinecone_collection` | `name` | — | API key | | `pinecone_collections` | — | — | API key | | `pinecone_project` | `id` | — | Service account | | `pinecone_projects` | — | — | Service account | | `pinecone_service_account` | `id` | — | Service account | | `pinecone_service_accounts` | — | — | Service account | | `pinecone_role_binding` | `id` | — | Service account | | `pinecone_role_bindings` | — | `principal_type`, `principal_id`, `resource_type`, `resource_id`, `role` | Service account | | `pinecone_invite` | `id` | — | Service account | | `pinecone_invites` | — | — | Service account | | `pinecone_user` | `id` or `email` | — | Service account | | `pinecone_users` | — | `email` | Service account | ```hcl Terraform theme={null} # Read one index by name data "pinecone_index" "example_index" { name = "example-index" } # The dimension of a vector index output "example_index_dimension" { value = data.pinecone_index.example_index.schema.fields["_values"].dense_vector.dimension } # List every index in the project data "pinecone_indexes" "all" {} # Look up a user by email, then grant them a project role data "pinecone_user" "example_user" { email = "teammate@example.com" } resource "pinecone_role_binding" "example_user_project_viewer" { principal_id = data.pinecone_user.example_user.id principal_type = "user" resource_type = "project" resource_id = "YOUR_PROJECT_ID" role = "ProjectViewer" } # List the role bindings held by one principal data "pinecone_role_bindings" "example_service_account_bindings" { principal_type = "service_account" principal_id = "YOUR_SERVICE_ACCOUNT_ID" } ``` Note the following behaviors: * `pinecone_index` and `pinecone_indexes` report each index's full `schema`, including the reserved vector fields and the metadata fields added as you upsert data. They also report `deployment`, top-level `read_capacity`, `private_host`, `cmek_id`, `source_backup_id`, and `source_collection`. * `dimension`, `metric`, and `vector_type` on the index data sources are derived from the schema, and are null when the schema doesn't determine a single value, as for an index with only full-text-search fields. They're planned for deprecation, so read `schema` instead. * For `pinecone_user`, set exactly one of `id` or `email`. Email matching is case-insensitive. * For `pinecone_role_bindings`, `principal_type` is required when you set `principal_id`, and `resource_type` is required when you set `resource_id`. You can't filter by a binding's own ID. Fetch it with the `pinecone_role_binding` data source instead. * `pinecone_invites` returns only `pending` and `expired` invites. To read an accepted invite, fetch it by ID with `pinecone_invite`. * The service account data sources never return client secrets. ## Import existing resources All resources support the [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import): | Resource | Import ID | | :- | :- | | `pinecone_index` | Index name | | `pinecone_collection` | Collection name | | `pinecone_project` | Project ID | | `pinecone_api_key` | `PROJECT_ID:API_KEY_ID` | | `pinecone_service_account` | Service account ID | | `pinecone_role_binding` | Role binding ID | | `pinecone_invite` | Invite ID | | `pinecone_user` | User ID | For example: ```bash theme={null} terraform import pinecone_user.example_user YOUR_USER_ID ``` Import stores document indexes in state in the `schema` style, and every other index in the `spec` style, however the index was created. You can still import a legacy vector index into a `schema` style configuration. The next plan [moves it](#move-an-index-to-the-schema-style) with the same state-only update. > [!NOTE] > > Provider v5.0.0 doesn't record integrated embedding when it imports a document index. After you upgrade to v5.1.0, a plan for such an index fails with `Integrated embedding can't be removed from a field`. To fix it, add `embed = {}` or `sparse_embed = {}` to the field so the configuration matches the index. The provider reads the model and other settings from the index, so the plan then shows no changes. Some attributes can't be imported because Pinecone returns them only once: * `pinecone_api_key.key` and `pinecone_service_account.client_secret` stay empty in state for an imported resource. To issue and store a new service account secret, change `rotate_trigger`. * `pinecone_invite.role_bindings` stays empty in state, and Terraform proposes a replacement on the next plan until you set it to match the original invite. Use the `pinecone_role_bindings` data source with `principal_type = "invite"` to see what the invite granted. ## Limitations The provider manages infrastructure only. You reference BYOC environments that Pinecone provisions for you. The provider doesn't support the following: * [Backups for serverless indexes](/guides/indexes/backups-overview), including restoring an index from a backup * Creating pod-based indexes, or creating an index from a collection * [Private endpoints](/guides/production/configure-private-endpoints) * [Assistants](/guides/assistant/overview) * BYOC environment provisioning * Data operations, such as upserting, querying, or deleting records and documents ## Resources * For the full provider documentation, see the [Terraform Registry](https://registry.terraform.io/providers/pinecone-io/pinecone/latest/docs). * For more usage examples, see the [GitHub repository](https://github.com/pinecone-io/terraform-provider-pinecone/tree/main/examples). * For support requests, create an issue in the [GitHub repository](https://github.com/pinecone-io/terraform-provider-pinecone). # Unstructured Source: https://docs.pinecone.io/integrations/unstructured Use Unstructured to parse, chunk, and load PDFs, Word, and 25+ document types into Pinecone for LLM-ready RAG ETL pipelines and semantic search apps. Unstructured builds ETL tools for LLMs, including an open-source Python library, a SaaS API, and an ETL platform. It extracts content and metadata from 25+ document types, including PDFs, Word documents, and PowerPoint files, and then performs preprocessing steps for LLMs, such as chunking. Unstructured maintains upstream connections to data sources such as SharePoint and Google Drive, and downstream connections to databases such as Pinecone. The Pinecone integration with Unstructured lets you load data from any source or document type into Pinecone with a single click, so you can build LLM apps that connect to your organization's data. [Get started](https://docs.unstructured.io/ui/destinations/pinecone-destination-quickstart) # Vercel Source: https://docs.pinecone.io/integrations/vercel Use the Pinecone integration for Vercel to connect your Vercel AI projects to Pinecone indexes for long-term memory and search. Vercel is a developer platform with the tools, workflows, and infrastructure you need to build and deploy web apps without additional configuration. Vercel supports popular frontend frameworks out of the box, and its infrastructure is globally distributed to serve content from data centers near your users. Pinecone provides long-term memory for your Vercel AI projects. The integration lets you set up and authenticate a connection to your Pinecone data and indexes, then scale to billions of data points. It's self-serve. You can keep the default settings or configure optional advanced settings. [Get started](https://vercel.com/integrations/pinecone) # VoltAgent Source: https://docs.pinecone.io/integrations/voltagent Build TypeScript AI agents with VoltAgent and Pinecone that use automatic embeddings, semantic search, and metadata filtering for observable RAG. [VoltAgent](https://voltagent.dev) is a TypeScript framework for building AI agents with retrieval-augmented generation (RAG). It supports two retrieval patterns, either searching automatically on every interaction or letting the LLM decide when to search, and includes built-in observability and tracking. This integration connects VoltAgent agents to Pinecone Database and generates embeddings automatically with OpenAI's API. It provides semantic search with similarity scoring, source tracking, metadata filtering, and namespace organization, and it supports serverless deployment with automatic scaling. The integration provides: * A complete RAG setup with sample data * Two pre-configured agent types * Automatic index creation and population * Source references and similarity scores * Production-ready architecture Use this integration to build AI agents that search and retrieve information from Pinecone indexes, with full observability and control over the retrieval process. [Get started](https://voltagent.dev/docs/rag/pinecone/) # Zapier Source: https://docs.pinecone.io/integrations/zapier Use Zapier to connect Pinecone to 6,000+ apps, trigger workflows when an index changes, and add data or run searches without writing code. [Zapier](https://zapier.com/) lets you connect Pinecone with thousands of popular apps and automate your work without writing code. With this integration, Pinecone can trigger workflows when your index status changes, and other apps can command Pinecone to perform actions. This means you can automatically add or remove data, run searches, or manage indexes based on events happening in your other tools. For example, you might use this integration to automatically add spreadsheet entries to your Pinecone index, or build a bot that searches for answers and posts them directly to your team chat. The integration brings Pinecone search and data operations into your existing workflows. [Get started](https://zapier.com/apps/pinecone/integrations) [View setup guide](https://help.zapier.com/hc/articles/38950923151117) # Model gallery Source: https://docs.pinecone.io/models/overview Compare the embedding and reranking models you can use with Pinecone by type, company, input, dimension, max tokens, and supported API. # Model gallery Embedding and reranking models you can use with your Pinecone API key, plus models you run yourself and bring as vectors. [Request a model](https://www.pinecone.io/request-a-model/) > [tab] Pinecone API key > > | Model | Company | Type | Input | Dimension | Max tokens | [Processing location](/guides/indexes/processing-locations) | Supported API | Minimum plan | Status | Actions | > | - | - | - | - | - | - | - | - | - | - | - | > | [gemini-embedding-2](/models/gemini-embedding-2) | Google | Dense embedding | Text | 128 to 3072 (default: 3072) | 8192 | `global` | Documents | Builder | | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=gemini-embedding-2\&dimensions=3072\&metric=cosine\&with_model=gemini-embedding-2) | > | [text-embedding-3-large](/models/text-embedding-3-large) | OpenAI | Dense embedding | Text | 1 to 3072 (default: 3072) | 8192 | `global` or `us` | Documents | Starter | | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=text-embedding-3-large\&dimensions=3072\&metric=cosine\&with_model=text-embedding-3-large) | > | [text-embedding-3-small](/models/text-embedding-3-small) | OpenAI | Dense embedding | Text | 1 to 1536 (default: 1536) | 8192 | `global` or `us` | Documents | Starter | | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=text-embedding-3-small\&dimensions=1536\&metric=cosine\&with_model=text-embedding-3-small) | > | [llama-text-embed-v2](/models/llama-text-embed-v2) | NVIDIA | Dense embedding | Text | 2048, 1024, 768, 512, 384 (default: 1024) | 2048 | `us` | Documents, Standalone embedding, Records | Starter | | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=llama-text-embed-v2\&dimensions=1024\&metric=cosine\&with_model=llama-text-embed-v2) | > | [multilingual-e5-large](/models/multilingual-e5-large) | Microsoft | Dense embedding | Text | 1024 | 507 | `us` | Documents, Standalone embedding, Records | Starter | | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=multilingual-e5-large\&dimensions=1024\&metric=cosine\&with_model=multilingual-e5-large) | > | [pinecone-sparse-english-v0](/models/pinecone-sparse-english-v0) | Pinecone | Sparse embedding | Text | Sparse | 2048 | `us` | Documents, Standalone embedding, Records | Starter | | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=pinecone-sparse-english-v0\&metric=dotproduct\&with_model=pinecone-sparse-english-v0) | > | [cohere-rerank-4-fast](/models/cohere-rerank-4-fast) | Cohere | Reranking | Text | N/A | 4096 | `global` | Standalone reranking, Records | Standard | | | > | [bge-reranker-v2-m3](/models/bge-reranker-v2-m3) | BAAI | Reranking | Text | N/A | 1024 | `us` | Standalone reranking, Records | Starter | | | > | [pinecone-rerank-v0](/models/pinecone-rerank-v0) | Pinecone | Reranking | Text | N/A | 512 | `us` | Standalone reranking, Records | Starter | Deprecated | | > > Documents: The [Documents API](/reference/api/2026-07/data-plane/upsert_documents), for document indexes with integrated embedding. > > Standalone embedding: The standalone [`/embed`](/reference/api/2026-07/inference/generate-vectors) endpoint, which embeds text without an index. > > Standalone reranking: The standalone [`/rerank`](/reference/api/2026-07/inference/rerank-results) endpoint, which reranks results without an index. > > Records: The legacy [Records API](/reference/api/2026-07/data-plane/upsert_records), for legacy integrated indexes created with `create_index_for_model`. > [tab] Bring your own vectors > > | Model | Company | Type | Input | Dimension | Max tokens | Actions | > | - | - | - | - | - | - | - | > | [gte-base](/models/gte-base) | Alibaba | Dense embedding | Text | 768 | 512 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=gte-base\&dimensions=768\&metric=cosine) | > | [gte-large](/models/gte-large) | Alibaba | Dense embedding | Text | 1024 | 512 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=gte-large\&dimensions=1024\&metric=cosine) | > | [embed-english-light-v3.0](/models/cohere-embed-english-light-v3.0) | Cohere | Dense embedding | Text | 384 | 512 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=embed-english-light-v3-0\&dimensions=384\&metric=cosine) | > | [embed-english-v3.0](/models/cohere-embed-english-v3.0) | Cohere | Dense embedding | Text | 1024 | 512 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=embed-english-v3-0\&dimensions=1024\&metric=cosine) | > | [embed-multilingual-v3.0](/models/cohere-embed-multilingual-v3.0) | Cohere | Dense embedding | Text | 1024 | 512 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=embed-multilingual-v3-0\&dimensions=1024\&metric=cosine) | > | [all-MiniLM-L12-v2](/models/all-MiniLM-L12-v2) | HuggingFace | Dense embedding | Text | 384 | 256 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=all-minilm-l12-v2\&dimensions=384\&metric=cosine) | > | [all-mpnet-base-v2](/models/all-mpnet-base-v2) | HuggingFace | Dense embedding | Text | 768 | 384 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=all-mpnet-base-v2\&dimensions=768\&metric=cosine) | > | [instructor-large](/models/instructor-large) | HuggingFace | Dense embedding | Text | 768 | 512 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=instructor-large\&dimensions=768\&metric=cosine) | > | [instructor-xl](/models/instructor-xl) | HuggingFace | Dense embedding | Text | 768 | 512 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=instructor-xl\&dimensions=768\&metric=cosine) | > | [jina-clip-v2](/models/jina-clip-v2) | Jina AI | Dense embedding | Text, image | 1024 | 8192 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=jina-clip-v2\&dimensions=1024\&metric=cosine) | > | [jina-embeddings-v4](/models/jina-embeddings-v4) | Jina AI | Dense embedding | Text, image | 2048, 128, 256, 512, 1024 | 32768 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=jina-embeddings-v4\&dimensions=2048\&metric=cosine) | > | [CLIP-ViT-B-32-laion2B-s34B-b79K](/models/CLIP-ViT-B-32-laion2B-s34B-b79K) | Laion | Dense embedding | Text, image | 512 | 77 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=clip-vit-b-32-laion2b-s34b-b79k\&dimensions=512\&metric=cosine) | > | [e5-base-v2](/models/e5-base-v2) | Microsoft | Dense embedding | Text | 768 | 512 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=e5-base-v2\&dimensions=768\&metric=cosine) | > | [e5-large-v2](/models/e5-large-v2) | Microsoft | Dense embedding | Text | 1024 | 512 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=e5-large-v2\&dimensions=1024\&metric=cosine) | > | [mistral-embed](/models/mistral-embed) | Mistral AI | Dense embedding | Text | 1024 | 8192 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=mistral-embed\&dimensions=1024\&metric=cosine) | > | [CLIP](/models/clip) | OpenAI | Dense embedding | Text, image | 512, 768 | 77 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=clip\&dimensions=512\&metric=cosine) | > | [text-embedding-ada-002](/models/text-embedding-ada-002) | OpenAI | Dense embedding | Text | 1536 | 8192 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=text-embedding-ada-002\&dimensions=1536\&metric=cosine) | > | [rerank-2](/models/rerank-2) | Voyage AI | Reranking | Text | N/A | 16000 | | > | [rerank-2-lite](/models/rerank-2-lite) | Voyage AI | Reranking | Text | N/A | 8000 | | > | [voyage-2](/models/voyage-02) | Voyage AI | Dense embedding | Text | 1024 | 4000 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=voyage-2\&dimensions=1024\&metric=cosine) | > | [voyage-3](/models/voyage-3) | Voyage AI | Dense embedding | Text | 1024 | 32000 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=voyage-3\&dimensions=1024\&metric=cosine) | > | [voyage-3-large](/models/voyage-3-large) | Voyage AI | Dense embedding | Text | 1024, 256, 512, 2048 | 32000 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=voyage-3-large\&dimensions=1024\&metric=cosine) | > | [voyage-3-lite](/models/voyage-3-lite) | Voyage AI | Dense embedding | Text | 512 | 32000 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=voyage-3-lite\&dimensions=512\&metric=cosine) | > | [voyage-code-2](/models/voyage-code-2) | Voyage AI | Dense embedding | Text | 1536 | 16000 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=voyage-code-2\&dimensions=1536\&metric=cosine) | > | [voyage-code-3](/models/voyage-code-3) | Voyage AI | Dense embedding | Text | 1024, 256, 512, 2048 | 32000 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=voyage-code-3\&dimensions=1024\&metric=cosine) | > | [voyage-finance-2](/models/voyage-finance-2) | Voyage AI | Dense embedding | Text | 1024 | 32000 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=voyage-finance-2\&dimensions=1024\&metric=cosine) | > | [voyage-large-2](/models/voyage-large-2) | Voyage AI | Dense embedding | Text | 1536 | 16000 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=voyage-large-2\&dimensions=1536\&metric=cosine) | > | [voyage-law-2](/models/voyage-law-2) | Voyage AI | Dense embedding | Text | 1024 | 16000 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=voyage-law-2\&dimensions=1024\&metric=cosine) | > | [voyage-multimodal-3](/models/voyage-multimodal-3) | Voyage AI | Dense embedding | Text, image | 1024 | 32000 | [Create index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless?name=voyage-multimodal-3\&dimensions=1024\&metric=cosine) | # Pinecone API 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](/admin/security/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; 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", "disabled", null); } } ``` ```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: 2026-07" \ -d '{ "name": "docs-example", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "_values": { "type": "dense_vector", "dimension": 1536, "metric": "cosine" } } } }' ``` ## Add headers to an HTTP request All HTTP requests to Pinecone APIs must contain an `Api-Key` header that specifies a valid [API key](/admin/security/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: 2026-07" \ -d '{ "name": "docs-example", "deployment": { "deployment_type": "managed", "cloud": "aws", "region": "us-east-1" }, "schema": { "fields": { "_values": { "type": "dense_vector", "dimension": 1536, "metric": "cosine" } } } }' ``` ## Troubleshooting > [accordion] Initialization errors due to outdated SDKs > > 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 overview Source: https://docs.pinecone.io/reference/api/database-limits Reference for Pinecone Database rate, object, operation, and identifier limits, plus known index and serverless limitations. This page describes the limits and known limitations for Pinecone Database. Each topic has its own reference page: * **[Rate limits](/reference/api/database-limits/rate-limits)**: request-per-second, monthly usage, and model throughput limits that vary by pricing plan, plus the `429` errors you get when you exceed them. * **[Object limits](/reference/api/database-limits/object-limits)**: the number or size of projects, users, indexes, namespaces, storage, backups, and collections allowed by plan. * **[Operation limits](/reference/api/database-limits/operation-limits)**: fixed batch-size limits for upsert, import, query, fetch, and delete, plus metadata filter limits. * **[Identifier limits](/reference/api/database-limits/identifier-limits)**: maximum length and allowed characters for organization, project, index, namespace, and record identifiers. * **[Known limitations](/reference/api/known-limitations)**: index and serverless caveats, such as upsert consistency and metadata rules. > [!NOTE] > > If a limit is blocking you, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. Many limits can be raised on request, and Support can often suggest a workaround for the ones that can't. # Identifier limits Source: https://docs.pinecone.io/reference/api/database-limits/identifier-limits Maximum length and allowed characters for Pinecone identifiers, including organization, project, index, namespace, and record names. An identifier is a string of characters used to identify "named" [objects in Pinecone](/guides/get-started/key-terms). The following Pinecone objects use strings as identifiers: | Object | Field | Max # characters | Allowed characters | | - | - | - | - | | [Organization](/guides/get-started/key-terms#organization) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Project](/guides/get-started/key-terms#project) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Index](/guides/get-started/key-terms#index) | `name` | 45 |
  • `a-z`, `0-9`, and `-`
  • Must be lowercase
  • Cannot start or end with `-`
  • Cannot be empty
| | [Namespace](/guides/get-started/key-terms#namespace) | `namespace` | 512 |
  • ASCII except `\0`
  • For the default namespace, use `""` (or `"__default__"`, in API versions `2025-04` and later)
| | [Namespace alias](/guides/data/namespace-aliases/overview) | `name` | 512 |
  • ASCII graphic characters
  • No spaces or `/ ? # % & = \ ; +`
  • `.`, `..`, and `__default__` are reserved
  • Must be unique in the index and can't match a namespace name
| | [Record](/guides/get-started/key-terms#record) | `id` | 512 |
  • ASCII except `\0`
  • Cannot be empty
| # Object limits Source: https://docs.pinecone.io/reference/api/database-limits/object-limits Limits on the number and size of Pinecone Database projects, indexes, namespaces, storage, backups, and collections, by plan. Object limits are restrictions on the number or size of objects in Pinecone. They vary based on [pricing plan](https://www.pinecone.io/pricing/). | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | Projects per organization | 1 | 5 | 20 | 100 | | Users per organization | 2 | 5 | Unlimited | Unlimited | | Serverless indexes per project 1 | 5 | 10 | 20 | 200 | | Serverless index storage per org | 2 GB | 10 GB | N/A | N/A | | Namespaces per serverless index | 100 | 1,000 | 100,000 | 1,000,000 | | Namespace aliases per serverless index | 1,000 | 1,000 | 1,000 | 1,000 | | Serverless backups per project | N/A | N/A | 500 | 1,000 | | 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/indexes/index-configuration#cloud-regions).\ When you exceed an object limit, API operations return a `403 - QUOTA_EXCEEDED`. [Upgrade your plan](/admin/billing/upgrade-billing-plan) to increase the limit. If a higher plan still doesn't cover what you need, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case, since most object limits can be raised on request. > [accordion] Example error > > ``` > Request failed. You've reached the max projects allowed in organization . > To add more projects, upgrade your plan. > ``` For the serverless storage limit, you can also [delete records](/guides/data/delete-data) to get back under it. > [!TIP] > > To stay under the serverless index limit, use [namespaces](/guides/indexes/create-an-index#namespaces) to partition data within a single index instead of creating multiple indexes. This can also improve query performance and lower costs by limiting searches to relevant data subsets. > [!NOTE] > > [Namespaces per serverless index](/reference/api/database-limits/object-limits) vary by plan (100 on Starter to 1,000,000 on Enterprise). Pinecone can accommodate more for specific use cases. If your application needs a higher limit, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). # Operation limits Source: https://docs.pinecone.io/reference/api/database-limits/operation-limits Fixed limits on Pinecone Database operations, including upsert, update, import, query, fetch, and delete batch sizes and metadata filter expressions. Operation limits are restrictions on the size, number, or other characteristics of operations in Pinecone. Operation limits are fixed and don't vary based on pricing plan. If one of these limits is blocking you, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. There's often a workaround. ## Upsert limits | Metric | Limit | | :- | :- | | Max [batch size](/guides/legacy/vectors-api/upsert-vectors#upsert-in-batches) for records with vectors | 1,000 records, up to 2 MB total | | Max batch size for records with text | 96 records | | Max documents per upsert request | 1,000, or 96 when the schema declares `embed` or `sparse_embed` | | 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](/guides/search/full-text-search/text-processing#tokens-and-analyzers) | 1,024 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 limit for text is lower because Pinecone converts that text to vectors at upsert time with [integrated embedding](/guides/indexes/index-data-overview#integrated-embedding), and 96 is the max batch size of the [hosted embedding models](/guides/indexes/index-configuration#embedding-models) doing the conversion. The 40 KB filterable metadata limit doesn't apply to `full_text_search` text fields. ## Update limits | Metric | Limit | | :- | :- | | Max documents per by-ID document update request | 1,000, or 96 when the schema declares `embed` or `sparse_embed` | | Max records per update-by-metadata request | 100,000 | ## Import limits > [!NOTE] > > If your import exceeds these limits, you'll get an error specifying the limit exceeded. See [Troubleshooting](/guides/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 doesn't apply to indexes with [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview). Bulk import supports indexes without a schema definition (Parquet files) and indexes with document schemas ([JSONL files](/guides/data/import-data#prepare-document-schema-files-jsonl)). Semantic-text (auto-embedded) fields aren't 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. > [!TIP] > > 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/legacy/vectors-api/fetch-vectors#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 returns 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 multitenancy](/guides/data/design-for-multitenancy). * **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 multitenancy](/guides/data/design-for-multitenancy#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. > [!TIP] > > 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. # Rate limits Source: https://docs.pinecone.io/reference/api/database-limits/rate-limits Request-per-second, monthly usage, and model throughput limits for Pinecone Database serverless indexes, and the 429 errors returned when you exceed them. Rate limits help protect your applications from misuse and maintain the health of our shared serverless infrastructure. They vary by [pricing plan](https://www.pinecone.io/pricing/) and apply to [serverless indexes](/guides/indexes/index-data-overview) only. Request-per-second limits are enforced per namespace or per index, as noted in the [Data operation throughput limits](#data-operation-throughput-limits) table, in addition to your read and write unit limits, so a request fails if it exceeds any applicable limit. When you exceed a limit, the request returns a `429 - TOO_MANY_REQUESTS` and the error message names the limit, scope, and value. **Most rate limits can be adjusted upon request.** If you need higher limits, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. > [!NOTE] > > Indexes built on [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) aren't subject to read unit limits for query, fetch, list, and full-text search operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) guide. ## Monthly usage limits [Read units](/guides/cost/understand-cost#read-units) and [write units](/guides/cost/understand-cost#write-units) measure resource consumption. To check your current usage, see [Download a usage report](/admin/billing/download-usage-report). | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | Read units per month per org | 1,000,000 | 2,000,000 | Unlimited | Unlimited | | Write units per month per org | 2,000,000 | 5,000,000 | Unlimited | Unlimited | | Embedding tokens per month per model | 5,000,000 | 10,000,000 | Unlimited | Unlimited | | `gemini-embedding-2` embedding tokens per month | Not available | 10,000,000 | Unlimited | Unlimited | > [!NOTE] > > From November 4 through December 31, 2026, Starter orgs get 10,000,000 embedding tokens per month per model, and Builder orgs get 20,000,000. Allowances return to the values in the table on January 1, 2027. Monthly rerank request limits vary by model: | Reranking model | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | `cohere-rerank-4-fast` | Not available | Not available | Unlimited | Unlimited | | `bge-reranker-v2-m3` | 500 | 1,000 | Unlimited | Unlimited | | `pinecone-rerank-v0` | 500 | Not available | Unlimited | Unlimited | Reaching a monthly usage limit returns a `429 - TOO_MANY_REQUESTS`. [Upgrade your plan](/admin/billing/upgrade-billing-plan) to continue. > [accordion] Example error > > ``` > Request failed. You've reached your read unit limit for the current month. > To continue reading data, upgrade your plan. > ``` ## Data operation throughput limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | Upsert size per second per namespace | 50 MB | 50 MB | 50 MB | 50 MB | | Query read units per second per namespace | 2,000 | 2,000 | 2,000 | 2,000 | | Query read units per second per index | 2,000 | 2,000 | 2,000 | 2,000 | | Query requests per second per namespace | 100 | 100 | 100 | 100 | | Update records per second per namespace | 100 | 100 | 100 | 100 | | Update requests per second per namespace | 100 | 100 | 100 | 100 | | Update by metadata requests per second per namespace | 20 | 20 | 20 | 20 | | Update by metadata requests per second per index | 500 | 500 | 500 | 500 | | Upsert requests per second per namespace | 100 | 100 | 100 | 100 | | Fetch requests per second per index | 100 | 100 | 100 | 100 | | List requests per second per index | 200 | 200 | 200 | 200 | | Describe index stats requests per second per index | 100 | 100 | 100 | 100 | | Delete requests per second per namespace | 100 | 100 | 100 | 100 | | Delete records per second per namespace | 5,000 | 5,000 | 5,000 | 5,000 | | Delete records per second per index | 5,000 | 5,000 | 5,000 | 5,000 | | Delete by metadata requests per second per namespace | 20 | 20 | 20 | 20 | | Delete by metadata requests per second per index | 500 | 500 | 500 | 500 | The per-namespace and per-index query read unit limits are enforced separately. At the defaults they're equal, so the namespace limit only matters once the index limit is raised. When you ask Support for a higher read limit, ask for both, or each namespace stays capped at its current limit. Exceeding a per-second throughput limit returns a `429 - TOO_MANY_REQUESTS`. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic), pace your requests, consider [Dedicated Read Nodes](/guides/optimize/dedicated-read-nodes/overview) (which aren't subject to per-second read limits) for high-throughput reads, or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) to raise a limit. > [accordion] Example 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. > ``` ## Model throughput limits Per-minute token limits for embedding models: | 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 | | `gemini-embedding-2` | Passage | Not available | 250,000 | 2,000,000 | 2,000,000 | | | Query | Not available | 50,000 | 250,000 | 250,000 | | `text-embedding-3-small` | Passage | 250,000 | 250,000 | 2,000,000 | 2,000,000 | | | Query | 50,000 | 50,000 | 250,000 | 250,000 | | `text-embedding-3-large` | Passage | 250,000 | 250,000 | 2,000,000 | 2,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 | Per-minute request limits for reranking models: | Reranking model | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | `cohere-rerank-4-fast` | Not available | Not available | 300 | 300 | | `bge-reranker-v2-m3` | 60 | 60 | 60 | 60 | | `pinecone-rerank-v0` | 60 | Not available | 60 | 60 | Reaching a per-minute model limit returns a `429 - TOO_MANY_REQUESTS`. [Upgrade your plan](/admin/billing/upgrade-billing-plan) to increase it, or [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). > [accordion] Example 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. > ``` ## Inference request limits | Metric | Starter plan | Builder plan | Standard plan | Enterprise plan | | :- | :- | :- | :- | :- | | Inference requests per second per project | 100 | 100 | 100 | 100 | | Inference requests per minute per project | 2,000 | 2,000 | 2,000 | 2,000 | These limits apply per project across all models. Every inference request counts toward them, including requests that a [per-minute token limit](#model-throughput-limits) then rejects. Exceeding the per-second or per-minute limit returns a `429 - TOO_MANY_REQUESTS`. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle it. > [accordion] Example error > > ``` > Request failed. You've reached the max inference requests per second () for the current project. > ``` > > The message names the per-second or per-minute limit, whichever you exceeded. # Pinecone API errors Source: https://docs.pinecone.io/reference/api/errors Look up the HTTP status codes the Pinecone API returns, plus the causes and fixes for common Pinecone API and SDK error messages. Look up an [HTTP status code](#http-status-codes), or find an exact error message under [Index creation errors](#index-creation-errors) or [Outdated Python SDK errors](#outdated-python-sdk-errors). For handling errors in production, see [Error handling](/guides/production/error-handling). ## HTTP status codes 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. ### 200 - OK The request succeeded. ### 201 - CREATED The request succeeded and a new resource was created. ### 202 - ACCEPTED The request was accepted, but the operation isn't complete yet. For example, deleting an index returns `202` while the deletion is still in progress. ### 204 - NO CONTENT The request succeeded, and there's no response body 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](/admin/projects/projects-overview#api-keys). ### 402 - PAYMENT REQUIRED The request failed due to delinquent payment or account deactivation for non-payment. See [Account deactivation for non-payment](/admin/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/indexes/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. ## Index creation errors ### Missing spec argument ```console theme={null} TypeError: Pinecone.create_index() missing 1 required positional argument: 'spec' ``` Python SDK versions 3.0.0 to 9.x require a `spec` argument in `create_index()`. Pass one to set the index's cloud and region: ```python Python theme={null} from pinecone import Pinecone, 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"), ) ``` In Python SDK 10, `spec` is optional and new indexes default to AWS `us-east-1`. For current syntax, see [Create an index](/guides/indexes/create-an-index). ### Serverless index limit reached ```console theme={null} Request failed. You've reached the max serverless indexes allowed in project PROJECT_NAME (LIMIT). Use namespaces to partition your data into logical groups, or upgrade your plan to add more serverless indexes. ``` The API returns this with status `403` when the project already has as many serverless indexes as your plan allows. For the limit on each plan, see [Object limits](/reference/api/database-limits/object-limits). To fix it, do one of the following: * [Delete indexes](/guides/indexes/manage-indexes#delete-an-index) you no longer need. * Store data in [namespaces](/guides/data/implement-multitenancy) within one index instead of creating separate indexes. * [Upgrade your plan](/admin/billing/upgrade-billing-plan). ## Outdated Python SDK errors These errors come from code written for Python SDK versions earlier than 3.0.0, or from having the deprecated `pinecone-client` package installed. ### Pinecone has no attribute init ```console theme={null} AttributeError: module 'pinecone' has no attribute 'init' ``` In Python SDK 5.0.0 and later, the message reads: ```console theme={null} AttributeError: init is no longer a top-level attribute of the pinecone package. Please create an instance of the Pinecone class instead. ``` The code calls `pinecone.init()`, which was removed in version 3.0.0. Create a client instance instead. It doesn't take an environment, only an API key: ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` The same applies to other former top-level functions, such as `pinecone.create_index()` and `pinecone.list_indexes()`. Call them on the client instance instead. ### Cannot import name Pinecone ```console theme={null} ImportError: cannot import name 'Pinecone' from 'pinecone' ``` The installed SDK is earlier than 3.0.0, or the deprecated `pinecone-client` package is installed alongside `pinecone`. The Python SDK package was renamed from `pinecone-client` to `pinecone`, and having both installed causes conflicts. Remove the old package and upgrade: ```shell Shell theme={null} pip uninstall pinecone-client pip install --upgrade pinecone ``` ### Controller hostname not found ```console theme={null} Failed to resolve 'controller.us-west-2.pinecone.io' controller.us-west-2-aws.pinecone.io not found Request failed to reach Pinecone while calling https://controller.us-west-2.pinecone.io/actions/whoami ``` SDK versions earlier than 3.0.0 send requests to environment-specific `controller` hostnames. Current SDKs use `https://api.pinecone.io`. Upgrade the SDK, then update your code as described in [Pinecone has no attribute init](#pinecone-has-no-attribute-init): ```shell Shell theme={null} pip install --upgrade pinecone ``` # 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. > [!NOTE] > > [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: > [card] [CLI](/reference/cli/overview) > [card] [Python SDK](/reference/sdks/python/overview) > [card] [Node.js SDK](/reference/sdks/node/overview) > [card] [Java SDK](/reference/sdks/java/overview) > [card] [Go SDK](/reference/sdks/go/overview) ## Inference Use the Inference API to generate vector embeddings and rerank results using [embedding models](/guides/indexes/index-configuration#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-results) and [Generate vectors](/reference/api/latest/inference/generate-vectors) 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: > [card] [Python SDK](/reference/sdks/python/overview) > [card] [Node.js SDK](/reference/sdks/node/overview) > [card] [Java SDK](/reference/sdks/java/overview) > [card] [Go SDK](/reference/sdks/go/overview) # 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. ## Upserts * Pinecone is eventually consistent, so there can be a slight delay before [upserted records](/guides/data/upsert-data) are available to query. After upserting records, use the [Get index stats](/reference/api/latest/data-plane/describeindexstats) operation to check whether 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/indexes/index-data-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 don't support sparse vectors. ## Metadata * Null metadata values aren't supported. Instead of setting a key to `null`, remove the key from the metadata payload. * Nested JSON objects aren't supported. ## Serverless indexes Serverless indexes don't support the following features: * [Filtering index statistics by metadata](/reference/api/latest/data-plane/describeindexstats) * [Private endpoints](/guides/production/configure-private-endpoints) * This feature is available on AWS only. # Pinecone API versioning Source: https://docs.pinecone.io/reference/api/versioning Learn how Pinecone versions its APIs by release date, how long each stable version is supported, and how to set the X-Pinecone-Api-Version header. 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: ![](https://mintcdn.com/pinecone/9qvQp5nU6duJvusQ/images/api-versioning.png?fit=max\&auto=format\&n=9qvQp5nU6duJvusQ\&q=85\&s=be4366853edee83e003c3863e31fa1ce) ## Specify an API version > [!WARNING] > > 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-07`) 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-07" ``` 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 [changelog](/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](/admin/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](/admin/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" ``` > [!WARNING] > > 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 > [!NOTE] > > 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" ``` > [!NOTE] > > 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). > [!NOTE] > > `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 > [accordion] pc login (Authenticate via user login) > > **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" > ``` > > > [!NOTE] > > > > This is an alias for `pc auth login`. Both commands perform the same operation. > [accordion] pc logout (Clear credentials / log out) > > **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 > ``` > > > [!NOTE] > > > > 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. > [accordion] pc target (Set target organization and project) > > **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 > ``` > [accordion] pc version (Show CLI version) > > **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 > ``` > [accordion] pc whoami (Show current user) > > **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 > ``` > > > [!NOTE] > > > > This is an alias for `pc auth whoami`. Both commands perform the same operation. ### Authentication > [accordion] pc auth clear (Clear specific credentials) > > **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 > ``` > > > [!NOTE] > > > > 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`. > [accordion] pc auth configure (Configure service account or API key) > > **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 > ``` > > > [!NOTE] > > > > `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). > [accordion] pc auth local-keys list (List managed keys) > > **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 > ``` > [accordion] pc auth local-keys prune (Delete managed keys) > > **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 > ``` > > > [!NOTE] > > > > This deletes keys from both local storage and Pinecone servers. Use `--dry-run` to preview before committing. > [accordion] pc auth login (Authenticate via user login) > > **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 > ``` > > > [!NOTE] > > > > 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`. > [accordion] pc auth logout (Clear authentication credentials) > > **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 > ``` > > > [!NOTE] > > > > 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. > [accordion] pc auth status (Show authentication status) > > **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 > ``` > [accordion] pc auth whoami (Show current user information) > > **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 > ``` > > > [!NOTE] > > > > This command does the same thing as `pc whoami`. ### Indexes > [accordion] pc index configure (Update index configuration) > > **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 > ``` > > > [!NOTE] > > > > Configuration changes may take some time to take effect. > [accordion] pc index create (Create a new index) > > **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 > ``` > > > [!NOTE] > > > > For a list of valid regions for a serverless index, see [Create a serverless index](/guides/indexes/create-an-index). > [accordion] pc index delete (Delete 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 > ``` > > > [!NOTE] > > > > This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. > [accordion] pc index describe (Show index details) > > **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 > ``` > [accordion] pc index stats (Show index statistics) > > **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 > ``` > [accordion] pc index list (List all indexes) > > **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 > [accordion] pc index namespace create (Create a namespace) > > **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 > ``` > [accordion] pc index namespace delete (Delete a namespace) > > **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 > ``` > > > [!WARNING] > > > > Deleting a namespace removes all vectors in that namespace. This operation cannot be undone. > [accordion] pc index namespace describe (Show namespace details) > > **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 > ``` > [accordion] pc index namespace list (List namespaces) > > **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 > [accordion] pc index vector delete (Delete 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 > ``` > > > [!NOTE] > > > > 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. > > > [!WARNING] > > > > Vector deletion is permanent and cannot be undone. > [accordion] pc index vector fetch (Fetch vectors by ID or filter) > > **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 > ``` > > > [!NOTE] > > > > Use either `--ids` or `--filter`, not both. When using `--ids`, pagination flags are not applicable. > [accordion] pc index vector list (List vector IDs) > > **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 > ``` > [accordion] pc index vector query (Query vectors) > > **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 > ``` > > > [!NOTE] > > > > Use `--id`, `--vector`, or sparse vectors (`--sparse-indices` and `--sparse-values`) to specify what to query against. These options are mutually exclusive. > [accordion] pc index vector update (Update vectors) > > **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"}' > ``` > > > [!NOTE] > > > > Use either `--id` for single vector updates or `--filter` for bulk updates. These options are mutually exclusive. > [accordion] pc index vector upsert (Upsert vectors) > > **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 > ``` > > > [!NOTE] > > > > **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 > [accordion] pc index record search (Search records in an index) > > **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..."} > ``` > [accordion] pc index record upsert (Upsert records into an integrated index) > > **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 > [accordion] pc index collection create (Create a collection from a pod-based index) > > **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 > ``` > [accordion] pc index collection delete (Delete a collection) > > **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 > ``` > > > [!NOTE] > > > > This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. > [accordion] pc index collection describe (Describe a collection by name) > > **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 > ``` > [accordion] pc index collection list (List collections in your project) > > **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 > [accordion] pc index backup create (Create a backup) > > **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 > ``` > [accordion] pc index backup delete (Delete a backup) > > **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 > ``` > > > [!NOTE] > > > > This command prompts for confirmation before deleting. Pass `--skip-confirmation` (or `--json`) to bypass the prompt in non-interactive contexts. > > > [!WARNING] > > > > Backup deletion is permanent and cannot be undone. > [accordion] pc index backup describe (Show backup details) > > **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 > ``` > [accordion] pc index backup list (List backups) > > **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 > ``` > [accordion] pc index restore (Restore an index from a backup) > > **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 > ``` > [accordion] pc index restore describe (Show restore job details) > > **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 > ``` > [accordion] pc index restore list (List restore jobs) > > **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 > [accordion] pc index import start (Start an import from a storage URI) > > **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 > ``` > [accordion] pc index import describe (Describe an import operation) > > **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 > ``` > [accordion] pc index import list (List import operations for an index) > > **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 - > ``` > [accordion] pc index import cancel (Cancel an in-progress import operation) > > **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 > [accordion] pc project create (Create a new project) > > **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" > ``` > [accordion] pc project delete (Delete a 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 > ``` > > > [!NOTE] > > > > 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. > [accordion] pc project describe (Show project details) > > **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 > ``` > [accordion] pc project list (List all projects) > > **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 > ``` > [accordion] pc project update (Update project settings) > > **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 > [accordion] pc organization delete (Delete an organization) > > **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 > ``` > > > [!NOTE] > > > > 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. > [accordion] pc organization describe (Show organization details) > > **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 > ``` > [accordion] pc organization list (List organizations) > > **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 > ``` > [accordion] pc organization update (Update organization settings) > > **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 > [accordion] pc api-key create (Create a new API key) > > **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 > ``` > > > [!NOTE] > > > > API keys are scoped to a specific organization and project. > [accordion] pc api-key delete (Delete an API key) > > **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 > ``` > > > [!NOTE] > > > > Deletion is permanent. Applications using this key immediately lose access to Pinecone. > [accordion] pc api-key describe (Show API key details) > > **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 > ``` > > > [!NOTE] > > > > Does not display the actual key value. > [accordion] pc api-key list (List all API keys) > > **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 > ``` > > > [!NOTE] > > > > Does not display key values. > [accordion] pc api-key update (Update API key settings) > > **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 > ``` > > > [!NOTE] > > > > Cannot change the actual key. If you need a different key, create a new one. ### Config > [accordion] pc config list (List all configuration settings and their current values) > > **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 > ``` > [accordion] pc config get \ (Get the current value of a configuration setting) > > **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 > ``` > [accordion] pc config describe \ (Show detailed information about a configuration setting) > > **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 > ``` > [accordion] pc config set \ \ (Set a configuration value) > > **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 > ``` > [accordion] pc config unset \ (Reset a configuration value to its default) > > **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 > [tab] macOS (Homebrew) > > ```bash theme={null} > brew tap pinecone-io/tap > brew install pinecone-io/tap/pinecone > ``` > [tab] Other platforms > > 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" ``` > [!TIP] > > 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 Set the Pinecone CLI target context with pc target to control which organization and project your commands run against, including in CI/CD and JSON mode. 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. | > [!NOTE] > > `--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 > [!WARNING] > > 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 can't 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 don't 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). > [card] [Python SDK](/reference/sdks/python/overview) > [card] [Node.js SDK](/reference/sdks/node/overview) > [card] [Java SDK](/reference/sdks/java/overview) > [card] [Go SDK](/reference/sdks/go/overview) ## 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-07` | `2026-04` | `2025-10` | `2025-04` | `2025-01` | `2024-10` | `2024-07` | `2024-04` | | - | :- | :- | :- | :- | :- | :- | :- | :- | | [Python SDK](/reference/sdks/python/overview) | v10.x | 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) | v9.x | v8.x | v7.x | v6.x | v5.x | v4.x | v3.x | v2.x | | [Java SDK](/reference/sdks/java/overview) | Coming soon | Coming soon | v6.x | v5.x | v4.x | v3.x | v2.x | v1.x | | [Go SDK](/reference/sdks/go/overview) | v7.x | 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. > [!NOTE] > > 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 search, query, fetch, and list responses. For example, if a search 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/monitor-performance) or the organization-wide [Usage dashboard](/admin/billing/download-usage-report). ## Community SDKs Find community-contributed SDKs for Pinecone. These libraries aren't 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. > [!TIP] > > 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-07` | v7.x | | `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/v7/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/v7/pinecone@ ``` To check your SDK version, run the following command: ```shell theme={null} go list -u -m all | grep go-pinecone ``` ## Upgrade > [!WARNING] > > Before upgrading to `v7.0.0`, update all relevant code to account for the following breaking changes. See the [v7 migration guide](https://github.com/pinecone-io/go-pinecone/blob/main/guides/migration/v7.md) for before-and-after examples. > > * Pod-based index creation is removed. `CreatePodIndex` and `CreatePodIndexRequest` no longer exist, but existing pod-based indexes keep working. > * Enum constants are prefixed with their type name. For example, `Aws` is now `CloudAWS`, and `Cosine` is now `IndexMetricCosine`. > * `ListImports` takes a `*ListImportsRequest`, and `QueryByVectorIdRequest.SparseValues` is removed. > * `SourceCollection` and `Schema` on the legacy create requests now return an error. `ConfigureIndexParams.Embed` is replaced by `ConfigureIndexParams.Schema`. > * `Backup` field types changed, and some invalid requests now fail client-side. > > If you are upgrading from `v2` or earlier, also account for the `v3.0.0` 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 `v6` to `v7` means changing: ```go theme={null} // before import "github.com/pinecone-io/go-pinecone/v6/pinecone" // after import "github.com/pinecone-io/go-pinecone/v7/pinecone" ``` Apart from the module path, `v5.0.0` and `v6.0.0` are backward compatible with the release lines before them. `v7.0.0` targets API version `2026-07` and includes the breaking changes listed above. To stay on API version `2026-04`, keep using `v6`. 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/v7/pinecone@latest ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/admin/security/security-overview#api-keys) to initialize a client instance: ```Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v7/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](/admin/security/manage-rbac), initialize an `AdminClient` with [service account](/admin/organizations/manage-service-accounts) credentials instead: ```Go theme={null} package main import ( "context" "log" "os" "github.com/pinecone-io/go-pinecone/v7/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) ``` > [!NOTE] > > 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)); ``` > [!TIP] > > 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) aren't currently instrumented. * **Bulk import operations** aren't yet instrumented. * **Server duration may be unavailable.** The `getServerDurationMs()` method returns `null` if the `x-pinecone-response-duration-ms` header isn't 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 don't 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 raised 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. > [!TIP] > > 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-10` | v6.x | | `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 6.3.0 # Gradle implementation "io.pinecone:pinecone-client:6.3.0" ``` Alternatively, you can download the standalone uberjar [pinecone-client-6.3.0-all.jar](https://repo1.maven.org/maven2/io/pinecone/pinecone-client/6.3.0/pinecone-client-6.3.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 > [!WARNING] > > Before upgrading from `v5.x` to `v6.x`, update code that passes enum values. Deletion protection, cloud, and import error mode now take strings, such as `"enabled"`, `"aws"`, and `"continue"`. For the full list of breaking changes, see the [`v6.0.0` release notes](https://github.com/pinecone-io/pinecone-java-client/releases/tag/v6.0.0). 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 6.3.0 # Gradle implementation "io.pinecone:pinecone-client:6.3.0" ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/admin/security/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. > [!TIP] > > 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.js SDK requires Node.js 22 or later. Its type declarations support TypeScript 5.2 to 7.x. The SDK is for server-side use only. Running it in a browser exposes your API key, so call Pinecone from your backend instead. ## 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-07` | v9.x | | `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 `v9.0.0` targets API version `2026-07`. To stay on API version `2026-04`, keep using `v8`. The flat control methods, such as `pc.createIndex` and `pc.configureIndex`, still work in `v9` but are deprecated in favor of resource clients such as `pc.indexes`. > [!WARNING] > > Before upgrading to `v9.0.0`, update all relevant code to account for the following breaking changes. See the [v9 migration guide](https://github.com/pinecone-io/pinecone-ts-client/blob/main/guides/upgrading/v9-migration.md) for before-and-after examples. > > * Node.js 22 or later is required. > * `pc.preview` and the `Preview*` exports are removed. Document operations move to `index.documents`, where `index` comes from `pc.index({ name, namespace })` or `pc.index(name).namespace(namespace)`. Control operations move to resource clients such as `pc.indexes`. > * Pod-based index creation, legacy metadata-indexing schemas, and the `sourceCollection` and `sourceBackupId` creation options are rejected. Existing pod-based indexes keep working. To restore from a backup, use `pc.backups.createIndex(backupId, options)`. > * A top-level `embed` option when configuring an index is rejected. Update the semantic field through a `schema.fields` patch instead. > * Legacy index response properties such as `dimension`, `metric`, and `spec` are compatibility getters derived from `schema` and `deployment`. They are omitted when a response is spread or serialized, and can throw `Errors.PineconeIndexPropertyError` when there is no legacy equivalent. > * `NamespaceDescription.recordCount` and `sizeBytes` are now decimal strings, and `BackupModel.createdAt` is now a `Date`. > * Some generated type names are renamed or removed. For example, `BackupPaginationResponse` is now `BackupListPagination`. 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](/admin/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](/admin/security/manage-rbac), initialize an `AdminClient` with [service account](/admin/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. > [!NOTE] > > 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. > [!TIP] > > 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`. The base install includes the sync and [async](#async-requests) clients and the [gRPC](https://grpc.io/) data-plane client, so there are no extras to install. ## Requirements The Pinecone Python SDK requires Python 3.10 or later. It has been tested with CPython versions from 3.10 to 3.14. ## 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 | | :- | :- | | `2026-07` | v10.x | | `2026-04` | v9.x | | `2025-10` | v8.x | | `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 ``` To install a specific version of the Python SDK, run the following command: ```shell pip theme={null} # Install a specific version pip install pinecone== ``` SDK versions 8.x and earlier shipped gRPC and asyncio support as optional extras. To use them on those versions, install `"pinecone[grpc]=="` or `"pinecone[asyncio]=="`. To check your SDK version, run the following command: ```shell pip theme={null} pip show pinecone ``` > [!NOTE] > > 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's 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 > [!WARNING] > > 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 ``` ## Initialize Once installed, you can import the library and then use an [API key](/admin/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/indexes/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's disabled when set to `False`. It's 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 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 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/indexes/index-data-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. > [tab] Python SDK without gRPC > > When using the Python SDK without gRPC, to get good performance, it's 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 aren't 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) > ``` > [tab] Python SDK with gRPC > > When using the Python SDK with gRPC, 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 with the [Python SDK](/reference/sdks/python/overview), use the `upsert_from_dataframe` method. It upserts in batches (set the size with `batch_size`), retries failed requests, and performs especially well with data loaded from Parquet files. The dataframe needs `id` and `values` columns, plus an optional `metadata` column. ```Python Python theme={null} import pandas as pd from pinecone import Pinecone pc = Pinecone(api_key="API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/indexes/target-an-index index = pc.Index(host="INDEX_HOST") # To load a Parquet file instead, use pd.read_parquet("path/to/file.parquet") df = pd.DataFrame({ "id": ["A", "B", "C"], "values": [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6], [0.7, 0.8, 0.9]], "metadata": [{"genre": "drama"}, {"genre": "comedy"}, {"genre": "drama"}], }) index.upsert_from_dataframe(df, namespace="example-namespace", batch_size=500) ``` # 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 > [tab] Databricks platform > > 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.2.0/spark-pinecone-uberjar.jar > ``` > > > [!NOTE] > > > > Databricks platform users must use the Pinecone assembly jar listed above to ensure that the proper dependecies are installed. > > 3. Click **Install**. > [tab] Databricks on AWS > > 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.2.0/spark-pinecone-uberjar.jar > ``` > > 3. Click **Install**. > [tab] Databricks on GCP / Azure > > 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.2.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() } ``` > [!TIP] > > 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) # Custom data processing agreements Source: https://docs.pinecone.io/admin/account/custom-data-processing-agreements Request a custom data processing agreement (DPA) with Pinecone if your team requires terms beyond the standard agreement available on the Pinecone website. To request a data processing agreement (DPA) with Pinecone, fill out the form in the Pinecone [Security Center](https://security.pinecone.io/). You'll need to request access first. Click **Get Access** on that page and enter your information. You should receive a link with further instructions shortly. # Delete your account Source: https://docs.pinecone.io/admin/account/delete-your-account Permanently delete your Pinecone account by removing your user from every organization and deleting any organization where you're the sole member. To delete your Pinecone account, you need to remove your user from all organizations and delete any organizations where you're the sole member. > [!WARNING] > > These actions cannot be undone. * [Remove yourself from an organization](/admin/organizations/manage-organization-members#remove-a-member) * [Delete an organization](/admin/organizations/delete-your-organization) Once you've removed yourself from or deleted all organizations associated with your user, your Pinecone account no longer exists. # Login code issues Source: https://docs.pinecone.io/admin/account/login-code-issues Fix a rejected Pinecone login code, which can expire after 10 hours or be invalidated by a shared inbox, a newer code request, or an offset system clock. If Pinecone doesn't accept the login code you received by email, check the following causes. ## The code has expired A code is valid for 10 hours. After that, Pinecone no longer accepts it. ## The code has already been used If you're using a shared email account or distribution list, check with your teammates to see if anyone else has used your code. ## A subsequent request was made If you're using a shared account, someone else may have requested a code after you did, which invalidates the first code. ## Your computer's system clock time is offset User authentication with a verification code relies on your device's system clock to verify the time. If your computer's clock is more than 10 minutes off from your time zone, the login will fail. If you see the following error message, set your system clock to the correct time and time zone before trying again. ``` Please check your computer's system clock time. See https://docs.pinecone.io/troubleshooting/login-code-issues for more information. ``` ## Your anti-spam filter followed the links in the email to check their validity If one of the links submitted the code as part of the URL, check with your anti-spam system admin or vendor to see if this might be the cause. # Access your invoices Source: https://docs.pinecone.io/admin/billing/access-your-invoices View and download your Pinecone organization billing invoices in the console, including invoice history, receipts, and payment records. 1. In the Pinecone console, go to [**Settings > Billing > Overview**](https://app.pinecone.io/organizations/-/settings/billing). 2. Scroll down to the **Payment history and invoices** section. 3. Next to the billing period you want, click **Download**. 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. # Billing disputes and refunds Source: https://docs.pinecone.io/admin/billing/billing-disputes-and-refunds Understand Pinecone's policy of not refunding unused indexes, and why migrating a pod-based index to serverless can lower a bill you'd otherwise dispute. As a rule, Pinecone doesn't offer refunds for unused indexes. If you use a pod-based index, Pinecone charges only for the pods you use to create it, not per API call or query. Whether or not you've used your index doesn't affect billing. Serverless indexes are a better fit if you don't plan to use your index on a regular basis. Serverless indexes are billed by the number of reads and writes you run and how much storage your index consumes. If your bill for your pod-based index is too high, we recommend [migrating to a serverless index](/guides/legacy/pod-based-indexes/migrate-a-pod-based-index-to-serverless) instead. Pinecone's billing policies are detailed in the [user agreement](https://www.pinecone.io/user-agreement/) and [pricing page](https://pinecone.io/pricing). These pages can help you manage your bill: * [Account deactivation for non-payment](/admin/billing/non-payment-account-deactivation) * [Change your billing plan](/admin/billing/upgrade-billing-plan) * [Download a usage report](/admin/billing/download-usage-report) * [Understand cost](/guides/cost/understand-cost) * [Save on Pinecone costs](/guides/cost/save-on-costs) # Change your payment method Source: https://docs.pinecone.io/admin/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. > [!NOTE] > > To change your payment method, you must be an [organization owner or billing admin](/admin/organizations/organizations-overview#organization-roles). > [!NOTE] > > The [Builder plan](https://www.pinecone.io/pricing/) is available with credit/debit card billing only and isn't supported through cloud marketplaces. To switch a Builder-plan organization to marketplace billing, first [upgrade to the Standard or Enterprise plan](/admin/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 > [tab] Credit card → Google Cloud > > 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**. > > > [!NOTE] > > > > The billing unit listed doesn't 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**. > > > [!NOTE] > > > > 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) and click **Create a ticket**. > 5. For **Topic**, select **Billing**, and for **Subtopic**, select **Change payment method**. > 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](/admin/organizations/manage-organization-members#add-a-member-to-an-organization). > 5. Downgrade your original Pinecone organization: > > > [!WARNING] > > > > Don't 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**. > > Your Pinecone usage is now billed through the Google Cloud Marketplace. > > > [!WARNING] > > > > You can [delete your original organization](/admin/organizations/delete-your-organization). However, before deleting, make sure to [download your past invoices](/admin/billing/access-your-invoices) since you will lose access to them once the organization is deleted. > [tab] Credit card → AWS > > 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**. > > > [!NOTE] > > > > The billing unit listed doesn't 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**. > > > [!NOTE] > > > > 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 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) and click **Create a ticket**. > 5. For **Topic**, select **Billing**, and for **Subtopic**, select **Change payment method**. > 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 AWS 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](/admin/organizations/manage-organization-members#add-a-member-to-an-organization). > 5. Downgrade your original Pinecone organization: > > > [!WARNING] > > > > Don't 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**. > > Your Pinecone usage is now billed through the AWS Marketplace. > > > [!WARNING] > > > > You can [delete your original organization](/admin/organizations/delete-your-organization). However, before deleting, make sure to [download your past invoices](/admin/billing/access-your-invoices) since you will lose access to them once the organization is deleted. > [tab] Credit card → Microsoft > > 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**. > > > [!NOTE] > > > > The billing unit listed doesn't 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 a 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**. > > > [!NOTE] > > > > 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 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) and click **Create a ticket**. > 5. For **Topic**, select **Billing**, and for **Subtopic**, select **Change payment method**. > 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](/admin/organizations/manage-organization-members#add-a-member-to-an-organization). > 5. Downgrade your original Pinecone organization: > > > [!WARNING] > > > > Don't 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**. > > Your Pinecone usage is now billed through the Microsoft Marketplace. > > > [!WARNING] > > > > You can [delete your original organization](/admin/organizations/delete-your-organization). However, before deleting, make sure to [download your past invoices](/admin/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 > [tab] Google Cloud → credit card > > 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) and click **Create a ticket**. > 3. For **Topic**, select **Billing**, and for **Subtopic**, select **Change payment method**. > 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](/admin/organizations/manage-organization-members#add-a-member-to-an-organization). > > 5. Downgrade your original Pinecone organization: > > > [!WARNING] > > > > Don't 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 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. > > > [!TIP] > > > > If you don't see the order, check that the correct billing account is selected. > > From now on, use your new organization. Your usage is billed to the credit card you provided. > > > [!WARNING] > > > > You can [delete your original organization](/admin/organizations/delete-your-organization). However, before deleting, make sure to [download your past invoices](/admin/billing/access-your-invoices) since you will lose access to them once the organization is deleted. > [tab] AWS → credit card > > 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) and click **Create a ticket**. > 3. For **Topic**, select **Billing**, and for **Subtopic**, select **Change payment method**. > 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](/admin/organizations/manage-organization-members#add-a-member-to-an-organization). > > 5. Downgrade your original Pinecone organization: > > > [!WARNING] > > > > Don't 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 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. > > From now on, use your new organization. Your usage is billed to the credit card you provided. > > > [!WARNING] > > > > You can [delete your original organization](/admin/organizations/delete-your-organization). However, before deleting, make sure to [download your past invoices](/admin/billing/access-your-invoices) since you will lose access to them once the organization is deleted. > [tab] Microsoft → credit card > > 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) and click **Create a ticket**. > 3. For **Topic**, select **Billing**, and for **Subtopic**, select **Change payment method**. > 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](/admin/organizations/manage-organization-members#add-a-member-to-an-organization). > > 5. Downgrade your original Pinecone organization: > > > [!WARNING] > > > > Don't 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. > > From now on, use your new organization. Your usage is billed to the credit card you provided. > > > [!WARNING] > > > > You can [delete your original organization](/admin/organizations/delete-your-organization). However, before deleting, make sure to [download your past invoices](/admin/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 > [tab] Any marketplace → Google Cloud > > 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**. > > > [!NOTE] > > > > The billing unit listed doesn't 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 change to Google Cloud Marketplace. > > > [!NOTE] > > > > 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. > > Your Pinecone usage is now billed through the Google Cloud Marketplace. > 3. Cancel your subscription in your previous marketplace: > > * For AWS: > 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. > * 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. > [tab] Any marketplace → AWS > > 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**. > > > [!NOTE] > > > > The billing unit listed doesn't 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. > > > [!NOTE] > > > > 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. > > Your Pinecone usage is now 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. > [tab] Any marketplace → Microsoft > > 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**. > > > [!NOTE] > > > > The billing unit listed doesn't 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 a 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. > > > [!NOTE] > > > > 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. > > Your Pinecone usage is now 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: 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 billing plan Source: https://docs.pinecone.io/admin/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. > [!NOTE] > > To change your billing plan, you must be an [organization owner or billing admin](/admin/organizations/organizations-overview#organization-roles). > [!TIP] > > If you're 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. ## Before you downgrade When you downgrade to the Starter plan in the Pinecone console, you choose which projects, indexes, assistants, and members to keep. You can keep up to the [Starter plan limits](/reference/api/database-limits/object-limits): 1 project, 5 serverless indexes in the `us-east-1` region of AWS, 5 assistants, and 2 members. Pinecone deletes everything you don't keep, along with all backups, backup schedules, and collections. The downgrade doesn't reduce your data or change your configuration, so do this first: * **Indexes outside `us-east-1`**: Indexes in other [regions](/guides/indexes/index-configuration#cloud-regions) can't be kept on Starter. To keep one, [create a new index](/guides/indexes/create-an-index) in `us-east-1`, [re-upsert your data](/guides/data/upsert-data), and delete the old index. * **Gemini and `us` processing indexes**: Indexes with embedded fields that use `gemini-embedding-2` or the `us` [processing location](/guides/indexes/processing-locations) can't be kept on Starter. To keep one, create a new index that uses a model available on Starter in place of `gemini-embedding-2`, or that sets `processing_location` to `global`. Then re-upsert your data and delete the old index. * **Dedicated read node indexes**: These can't run on Starter, and there's no self-serve conversion. To keep one in `us-east-1`, [back it up](/guides/indexes/back-up-an-index) and [restore it](/guides/indexes/restore-an-index), which creates a new on-demand serverless index in the same region. Delete the original and keep the restored index during the downgrade. For one in another region, create a new `us-east-1` index and re-upsert your data. You can also [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) to migrate back. * **Pod-based indexes**: To keep one, [migrate it to serverless](/guides/legacy/pod-based-indexes/migrate-a-pod-based-index-to-serverless) and finish creating the new serverless index first. The migration saves your index as a collection, and the downgrade deletes all collections. * **`eu` assistants**: These are deleted unless you move them. To keep one, [recreate it in `us`](/guides/assistant/create-assistant) and re-upload its files. * **SSO**: Disconnect your organization's [SSO connection](/admin/organizations/organizations-overview#organization-single-sign-on-sso). * **Member roles**: Reassign or remove members whose [organization role](/admin/organizations/organizations-overview#organization-roles) isn't available on Starter. * **Storage**: Starter allows no more than 2 GB of data across your serverless indexes and 1 GB of assistant storage. [Delete records](/guides/data/delete-data) and [assistant files](/guides/assistant/manage-files#delete-a-file) to fit. Do this last, because the migrations above can briefly leave a second copy of an index. > [!NOTE] > > You don't need to bring [Assistant usage](/guides/assistant/pricing-and-limits) (ingestion units, chat tokens, and context tokens) under Starter caps before downgrading. If you exceed Starter limits after downgrading, new requests may be blocked until usage is within limits. > [!NOTE] > > If you're switching from Standard to Builder instead of Starter, your organization must be under the [Builder plan quotas](/reference/api/database-limits/object-limits). You must also delete all backups and remove or stop any features not available on Builder, such as bulk import, pod-based indexes, storage integrations, RBAC, and SSO. ## Downgrade to the Starter plan The downgrade process is different depending on how you're paying for Pinecone. > [!WARNING] > > Start the downgrade in the Pinecone console, as described below. The console walks you through what to keep and cleans up the rest. If you start the downgrade in a cloud marketplace instead, that cleanup doesn't run, so Pinecone deactivates your account and you'll need to [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). > [tab] Credit card > > 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 ends immediately, but you'll receive a final invoice for any charges accrued in the current month. > [tab] Google Cloud Marketplace > > 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 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. > > > [!TIP] > > > > If you don't see the order, check that the correct billing account is selected. > > Your billing ends immediately, but you'll receive a final invoice for any charges accrued in the current month. > [tab] AWS Marketplace > > 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 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 ends immediately, but you'll receive a final invoice for any charges accrued in the current month. > [tab] Microsoft Marketplace > > 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 Azure 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 ends immediately, but you'll receive a final invoice for any charges accrued in the current month. ## Switch from Standard to Builder If you're on the Standard plan and pay by credit/debit card, you can switch to the [Builder plan](/reference/api/database-limits/object-limits) for a flat \$20/month: 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. Instead, requests that exceed Builder quotas are blocked. If you need more capacity, [upgrade back to Standard or Enterprise](/admin/billing/upgrade-billing-plan) at any time. > [!NOTE] > > The [Builder plan](https://www.pinecone.io/pricing/) is available with credit/debit card billing only and isn't supported through cloud marketplaces. If you pay through a cloud marketplace, you can't 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/admin/billing/download-usage-report Download a usage and cost report for your Pinecone organization from the console, or export one with the Admin API. > [!NOTE] > > To view usage and costs across your Pinecone organization, you must be an [organization owner or billing admin](/admin/organizations/organizations-overview#organization-roles). Also, this feature is available only to organizations on the Standard or Enterprise plans. The **Usage** dashboard in the Pinecone console reports usage and costs across your organization. On the page you can group the charts by SKU or project and switch the cost distribution between services. The CSV download covers whichever time range you select, regardless of how you group the charts. > [tab] Pinecone console > > 1. In the top-right navigation of the Pinecone console, go to [**Settings > Usage**](https://app.pinecone.io/organizations/-/settings/usage). > 2. Select the time range to report on. This defaults to the current month, or to the previous month during the first five days of a month. > 3. Click **Download**. > > On Standard plans, the report downloads right away. > > On Enterprise plans, choose **Download CSV** from the menu. The export runs in the background and appears in the list on the page. When it finishes, click **Click to download** on its entry. > > > [!TIP] > > > > The download provides more granular detail than the console view, including breakdowns by individual index as well as project and index tags. > > On Enterprise plans, exports you create through the Admin API appear in that same list. > [tab] Code > > > [!NOTE] > > > > Exporting through the Admin API is available only on [Enterprise plans](https://www.pinecone.io/pricing/) and requires an [access token](/admin/organizations/manage-service-accounts#retrieve-an-access-token). > > Exporting with the Admin API takes three requests: create the export, poll it until it finishes, then download the file. > > **1. Create the export** > > An export covers whole UTC calendar days, each written as `YYYY-MM-DD`. `period_start` is the first day you want and can be no earlier than 365 days before today. `period_end` is the day *after* the last day you want, so `2026-08-01` through `2026-09-01` covers all of August. Omit the request body to export the trailing 30 complete days. > > ```bash curl theme={null} > PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" > > curl -X POST "https://api.pinecone.io/admin/cost-usage-exports" \ > -H "X-Pinecone-Api-Version: 2026-07" \ > -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ > -H "Content-Type: application/json" \ > -d '{ > "period_start": "2026-08-01", > "period_end": "2026-09-01" > }' > ``` > > The export is recorded but hasn't run yet, so the response returns `"status": "Pending"` and the file fields are empty: > > ```json theme={null} > { > "id": "9f2c1a4e-8b3d-4c5f-a1b2-c3d4e5f6a7b8", > "status": "Pending", > "format": "zip", > "period_start": "2026-08-01", > "period_end": "2026-09-01", > "data_available_through": null, > "row_count": null, > "size_bytes": null, > "download_url": null, > "download_url_expires_at": null, > "file_expires_at": null, > "file_expired": false, > "error": null, > "created_at": "2026-09-02T14:31:07.482910355Z", > "started_at": null, > "finished_at": null, > "updated_at": "2026-09-02T14:31:07.482910355Z" > } > ``` > > An organization can run only one export at a time. Starting another while one is `Pending` or `InProgress` returns a `409`. An organization can also start at most five exports per hour. Going over that returns a `429` with a `Retry-After` header. > > **2. Poll until the export finishes** > > Use the `id` from the previous step to check on the export. > > ```bash curl theme={null} > EXPORT_ID="9f2c1a4e-8b3d-4c5f-a1b2-c3d4e5f6a7b8" > > curl -X GET "https://api.pinecone.io/admin/cost-usage-exports/$EXPORT_ID" \ > -H "X-Pinecone-Api-Version: 2026-07" \ > -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" > ``` > > `status` moves from `Pending` to `InProgress`, and then to either `Completed` or `Failed`. Both of those are terminal and never change afterward. When the export completes, the response carries the file's size, row count, and download link: > > ```json theme={null} > { > "id": "9f2c1a4e-8b3d-4c5f-a1b2-c3d4e5f6a7b8", > "status": "Completed", > "format": "zip", > "period_start": "2026-08-01", > "period_end": "2026-09-01", > "data_available_through": "2026-08-31", > "row_count": 48213, > "size_bytes": 4183902, > "download_url": "https://storage.googleapis.com/example-bucket/cost_usage_exports/export.zip?X-Goog-Expires=3600&X-Goog-Signature=abc123", > "download_url_expires_at": "2026-09-02T15:36:11.237604891Z", > "file_expires_at": "2026-09-04T14:35:52.904155718Z", > "file_expired": false, > "error": null, > "created_at": "2026-09-02T14:31:07.482910355Z", > "started_at": "2026-09-02T14:31:19.118374902Z", > "finished_at": "2026-09-02T14:35:52.904155718Z", > "updated_at": "2026-09-02T14:36:11.237604891Z" > } > ``` > > `data_available_through` is the date of the most recent usage row in the export. Because cost data lags behind usage, it can be earlier than the `period_end` you asked for. > > **3. Download the file** > > `download_url` is a signed link to a zip archive. The archive holds the cost records as one or more CSV files whose columns follow the [FOCUS v1.4](https://focus.finops.org/) Cost and Usage dataset. Each CSV starts with a header line and holds at most 800,000 rows, so a large export is split across several files, named `part-1-of-3.csv` through `part-3-of-3.csv` and ordered by those names. The numbers are zero-padded once an export runs to ten or more parts, so a 12-part export starts at `part-01-of-12.csv`. > > The archive also holds a `manifest.json` listing the export's window, `row_count`, the 45 column names, and each part with its own row count. > > FOCUS uses its own names for the things being billed, so Pinecone's organization, project, and index appear under FOCUS columns rather than under the headings you see in the console: > > | Pinecone | FOCUS columns | > | - | - | > | Organization | `x_OrganizationId` for the ID, `BillingAccountName` for the name | > | Project | `SubAccountId`, `SubAccountName` | > | Resource | `ResourceId`, `ResourceName`, with `ResourceType` naming the kind | > > `BillingAccountId` holds your billing customer ID, which isn't the same as your Pinecone organization ID. > > Most rows describe an index, but an export also covers other resources, so `ResourceType` can be `index`, `assistant`, `backup`, `collection`, or `model`. Rows for fixed fees leave it empty. > > Columns prefixed with `x_` are Pinecone extensions, which is how FOCUS requires a provider to name a column the specification doesn't define. For the full column list, see [Create a cost usage export](/reference/api/latest/admin/cost-usage-exports/create-a-cost-usage-export). > > ```bash curl theme={null} > DOWNLOAD_URL="YOUR_DOWNLOAD_URL" > > curl -o cost-usage-export.zip "$DOWNLOAD_URL" > ``` > > Pinecone generates a new link each time you read a single export, and each link is valid for one hour. `download_url_expires_at` tells you when the current one stops working. To get a fresh link, read the export again. Treat the link as a secret while it's valid, since anyone who has it can download the file. > > Pinecone deletes the file itself two days after the export finishes, and you can't download it again. Check `file_expired` rather than `status` to know whether the file is still there, because a `Completed` export whose file has expired can no longer be downloaded. Create another export instead. > > To see the exports your organization has already run, use [List cost usage exports](/reference/api/latest/admin/cost-usage-exports/list-cost-usage-exports). List responses always return `download_url` as `null`, so read a single export when you need a link. 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/admin/billing/non-payment-account-deactivation Learn what happens when Pinecone deactivates an account for non-payment, how long data is retained, 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 can't 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 can't be undone. > [!NOTE] > > 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). When your account is deactivated, organization owners see this notice in the Pinecone console: > **Your account has been deactivated** > > Due to an unresolved payment issue, your account was deactivated and all running indexes have been archived. Please update your payment information to reactivate. Other organization members see a message asking them to contact an organization owner. ## 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 > Overview**](https://app.pinecone.io/organizations/-/settings/billing). 3. Update your payment information or resolve the outstanding balance. Organization [owners and billing admins](/admin/organizations/organizations-overview#organization-roles) can update billing details. For help changing how you pay, see [Change your payment method](/admin/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](/admin/billing/change-payment-method) * [Data deletion on Pinecone](/guides/production/data-deletion) * [Billing disputes and refunds](/admin/billing/billing-disputes-and-refunds) # Redeem a promo code Source: https://docs.pinecone.io/admin/billing/redeem-a-promo-code Learn how to redeem a Pinecone promo code when you upgrade to the Builder plan, and how to fix common redemption errors. Pinecone promo codes, also called discount codes, discount the Builder plan. You enter a code while upgrading an organization from Starter to Builder, and you can't add one after the organization is on a paid plan. ## Before you start Each code works for one email address and one plan, and only until its redemption date. * Sign in with the email address the code was sent to. The code doesn't work for anyone else, even a teammate in the same organization. * Select the organization you want to discount. The code applies to whichever organization is selected when you upgrade. To switch, click the organization name at the top left of the console. * Make sure that organization is on the Starter plan and isn't in an active [Standard trial](/admin/billing/standard-trial). * Make sure you're an organization owner or billing admin. Other [organization roles](/admin/organizations/organizations-overview#organization-roles) can't change the plan. * Make sure the code hasn't expired. Codes look like `BUILDER-20261231-0A1B2C3D4E5F`, where the 8-digit date is the last day you can redeem it, in UTC. ## Redeem a code 1. In the Pinecone console, go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans). 2. In the **Builder** plan section, click **Upgrade**. 3. In the **Continue on Builder** dialog, click **Add discount code**. 4. Paste your code and click **Add code**. Letter case and extra spaces don't matter. 5. Click **Continue**. 6. Enter your credit or debit card information and click **Upgrade**. The dialog shows **Discount code applied** for any code you add, valid or not. Pinecone checks the code when you click **Upgrade**, and if the code is rejected, the upgrade doesn't go through and you aren't charged. ## After you redeem a code When the upgrade succeeds, the console confirms that your discount code has been applied. The cost table in the upgrade dialog still shows the full \$20/month, because the discount is applied to your [invoices](/admin/billing/access-your-invoices). While the discount is active, the plan card on [**Settings > Billing > Overview**](https://app.pinecone.io/organizations/-/settings/billing) shows the date it ends. Pinecone emails you 5 days before that date and again when the discount ends. After that, Builder is billed at the regular price. The discount only applies to the Builder plan. If you move the organization to another plan, the discount ends. If the upgrade dialog offers a Builder launch promotion, your code replaces it. ## Troubleshoot redemption errors | Message or symptom | Cause | Fix | | - | - | - | | "Failed to upgrade. Discount code is not valid for this account." | The code has a typo, is for a plan other than Builder, or was sent to a different email address than the one you're signed in with. | Paste the code exactly as you received it, and check that it starts with `BUILDER-`. Sign in with the email address the code was sent to. | | "Failed to upgrade. Discount code has expired." | The redemption date in the code has passed. | [Contact support](/admin/support/contact-support) if you think the code should still be valid. | | "Failed to upgrade. A subscription already exists for this organization." | The selected organization is already on a paid plan. | Select an organization on the Starter plan. To discount an existing subscription, [contact support](/admin/support/contact-support). | | The Add discount code link is missing | The organization isn't on Starter or is in an active Standard trial, or you clicked **Upgrade** on a plan other than Builder. | Check which organization is selected and its current plan, and then click **Upgrade** in the **Builder** plan section. | | The Upgrade button is disabled | You aren't an owner or billing admin, or the organization is billed through a cloud marketplace. | Ask an organization owner to upgrade or to give you the billing admin role. If the organization is billed through a cloud marketplace, [contact support](/admin/support/contact-support). | ## Contact support [Contact support](/admin/support/contact-support) if you upgraded without entering your code, applied it to the wrong organization, or your code was sent to an email address you don't use to sign in. Include the code, the organization name, and the email address you sign in with. # Pinecone Standard plan trial Source: https://docs.pinecone.io/admin/billing/standard-trial Evaluate the Pinecone Standard plan with $300 in credits over 21 days, including bulk import, backup and restore, RBAC, and higher scale limits. The Standard trial lets you evaluate Pinecone without 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/object-limits) that are suitable for testing Pinecone at scale. > [!NOTE] > > 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/data/import-data) * [Backup and restore](/guides/indexes/backups-overview) * [RBAC (role-based access control)](/admin/security/security-overview#role-based-access-controls-rbac) * [Higher limits](/reference/api/database-limits/object-limits) for testing at scale * Access to all [cloud regions](/guides/indexes/index-configuration#cloud-regions) * Access to [Developer Support](https://www.pinecone.io/pricing/?plans=support) ## Expiration When your Standard trial ends, or when you use all of your credits, your quotas are blocked and console access is limited to the billing page. You don't automatically return to your previous plan. To restore full access, do one of the following: * Add a payment method and continue on the Standard plan. * Upgrade to the Enterprise plan. * [Downgrade to the Starter plan](#downgrade-to-the-starter-plan) (you can also do this any time before the trial expires). If you started the trial from the Builder plan, you aren't charged the \$20/month Builder fee during the trial. > [!NOTE] > > Learn more about [pricing](https://www.pinecone.io/pricing/). ## Downgrade to the Starter plan You can downgrade from a Standard trial to the Starter plan at any time. When you downgrade to the Starter plan in the Pinecone console, you choose which projects, indexes, assistants, and members to keep. You can keep up to the [Starter plan limits](/reference/api/database-limits/object-limits): 1 project, 5 serverless indexes in the `us-east-1` region of AWS, 5 assistants, and 2 members. Pinecone deletes everything you don't keep, along with all backups, backup schedules, and collections. The downgrade doesn't reduce your data or change your configuration, so do this first: * **Indexes outside `us-east-1`**: Indexes in other [regions](/guides/indexes/index-configuration#cloud-regions) can't be kept on Starter. To keep one, [create a new index](/guides/indexes/create-an-index) in `us-east-1`, [re-upsert your data](/guides/data/upsert-data), and delete the old index. * **Gemini and `us` processing indexes**: Indexes with embedded fields that use `gemini-embedding-2` or the `us` [processing location](/guides/indexes/processing-locations) can't be kept on Starter. To keep one, create a new index that uses a model available on Starter in place of `gemini-embedding-2`, or that sets `processing_location` to `global`. Then re-upsert your data and delete the old index. * **Dedicated read node indexes**: These can't run on Starter, and there's no self-serve conversion. To keep one in `us-east-1`, [back it up](/guides/indexes/back-up-an-index) and [restore it](/guides/indexes/restore-an-index), which creates a new on-demand serverless index in the same region. Delete the original and keep the restored index during the downgrade. For one in another region, create a new `us-east-1` index and re-upsert your data. You can also [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) to migrate back. * **Pod-based indexes**: To keep one, [migrate it to serverless](/guides/legacy/pod-based-indexes/migrate-a-pod-based-index-to-serverless) and finish creating the new serverless index first. The migration saves your index as a collection, and the downgrade deletes all collections. * **`eu` assistants**: These are deleted unless you move them. To keep one, [recreate it in `us`](/guides/assistant/create-assistant) and re-upload its files. * **SSO**: Disconnect your organization's [SSO connection](/admin/organizations/organizations-overview#organization-single-sign-on-sso). * **Member roles**: Reassign or remove members whose [organization role](/admin/organizations/organizations-overview#organization-roles) isn't available on Starter. * **Storage**: Starter allows no more than 2 GB of data across your serverless indexes and 1 GB of assistant storage. [Delete records](/guides/data/delete-data) and [assistant files](/guides/assistant/manage-files#delete-a-file) to fit. Do this last, because the migrations above can briefly leave a second copy of an index. > [!NOTE] > > You don't need to bring [Assistant usage](/guides/assistant/pricing-and-limits) (ingestion units, chat tokens, and context tokens) under Starter caps before downgrading. If you exceed Starter limits after downgrading, new requests may be blocked until usage is within limits. > [!NOTE] > > If you're switching from Standard to Builder instead of Starter, your organization must be under the [Builder plan quotas](/reference/api/database-limits/object-limits). You must also delete all backups and remove or stop any features not available on Builder, such as bulk import, pod-based indexes, storage integrations, RBAC, and SSO. ## Limits * Each organization is allowed only one trial. * Organizations already on a Standard or Enterprise plan can't activate a Standard plan trial. * Organizations that initially subscribed to Pinecone through marketplace partners can't activate a Standard plan trial. If you have questions, [contact Support](https://www.pinecone.io/contact/support/). # Upgrade your billing plan Source: https://docs.pinecone.io/admin/billing/upgrade-billing-plan Upgrade your Pinecone organization to the Builder, Standard, or Enterprise plan and pay by card or through a cloud marketplace. This page describes how to upgrade to a paid [Builder, Standard, or Enterprise plan](https://www.pinecone.io/pricing/), either from the free Starter plan or from Builder to Standard or Enterprise. You can pay with a credit or debit card, or through a supported cloud marketplace if your organization is on the Starter plan. > [!NOTE] > > To change your plan, you must be an [organization owner or billing admin](/admin/organizations/organizations-overview#organization-roles). > [!TIP] > > To evaluate the Standard plan before you start paying, see the [Standard plan trial](/admin/billing/standard-trial). You get 21 days and \$300 in credits. Each organization can activate one trial, and [some organizations aren't eligible](/admin/billing/standard-trial#limits). > [!TIP] > > 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. If you have a promo code, click **Add discount code** and enter it. For details, see [Redeem a promo code](/admin/billing/redeem-a-promo-code). 4. Click **Continue**. 5. Enter your credit or debit card information. 6. Click **Upgrade**. After upgrading, your organization is immediately on the Builder plan with the higher [Builder plan quotas](/reference/api/database-limits/object-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. > [!NOTE] > > The [Builder plan](https://www.pinecone.io/pricing/) is available with credit/debit card billing only and isn't supported through cloud marketplaces. ## Upgrade to the Standard or Enterprise plan ### Pay with a credit/debit card 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'll 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 [Understand Pinecone cost](/guides/cost/understand-cost). ### Pay through the Google Cloud Marketplace 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**. > [!NOTE] > > The billing unit listed doesn't 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/). You can also create a new organization. 9. Click **Connect to Pinecone** and follow the prompts. After your organization is connected and upgraded, you'll receive a confirmation message. You'll 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 [Understand Pinecone cost](/guides/cost/understand-cost). ### Pay through the AWS Marketplace 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**. > [!NOTE] > > The billing unit listed doesn't 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. > [!WARNING] > > 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 doesn't 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/). You can also create a new organization. 9. Click **Connect to Pinecone** and follow the prompts. After your organization is connected and upgraded, you'll receive a confirmation message. You'll 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 [Understand Pinecone cost](/guides/cost/understand-cost). ### Pay through the Microsoft Marketplace 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**. > [!NOTE] > > The billing unit listed doesn't 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 a 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/). You can also create a new organization. 12. Click **Connect to Pinecone** and follow the prompts. After your organization is connected and upgraded, you'll receive a confirmation message. You'll 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 [Understand Pinecone cost](/guides/cost/understand-cost). # Delete your organization Source: https://docs.pinecone.io/admin/organizations/delete-your-organization Permanently delete a Pinecone organization after you delete its indexes, collections, and projects and downgrade to the Starter plan. Before you can delete your Pinecone organization, you need to delete all of its projects and downgrade to the Starter plan. To delete a project, first delete its indexes and collections. * [Delete an index](/guides/indexes/manage-indexes#delete-an-index) * [Delete a project](/admin/projects/manage-projects#delete-a-project) * [Downgrade to the Starter plan](/admin/billing/downgrade-billing-plan) Once you've downgraded to the Starter plan and deleted your indexes and projects, you can delete your organization. > [!WARNING] > > This action cannot be undone. 1. In the Pinecone console, go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage). 2. Click **Delete this organization**. 3. Type the organization name and confirm the deletion. # Manage organization members Source: https://docs.pinecone.io/admin/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](/admin/organizations/organizations-overview#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](/admin/security/manage-rbac). > [!TIP] > > For information about managing members at the project level, see [Manage project members](/admin/projects/manage-project-members). ## Add a member to an organization 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**](/admin/organizations/organizations-overview#organization-roles) for the member. The role determines the member's permissions within Pinecone. 4. Click **Invite**. When you invite a member, Pinecone emails them an invite link, whether or not they already have a Pinecone account. They join the organization when they accept the invite. Until then, the invite appears in the **Invites** list on the **Members** page. ## Change a member's role 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**](/admin/organizations/organizations-overview#organization-roles) for the member. 4. Click **Save**. ## Remove a member 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**. > [!NOTE] > > To remove yourself from an organization, in your user's row, click **ellipsis (...) menu > Leave organization** and confirm. If you're the only owner, you can't leave. # Manage organization service accounts Source: https://docs.pinecone.io/admin/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. > [!NOTE] > > This feature is available on the [Enterprise plan](https://www.pinecone.io/pricing/). This page shows how [organization owners](/admin/organizations/organizations-overview#organization-roles) can add and manage service accounts at the organization level. Service accounts enable programmatic access to Pinecone's Admin API, which you can use to create and manage projects and API keys. > [!TIP] > > Once you add a service account at the organization level, you can add it to a project. For more information, see [Manage service accounts at the project level](/admin/projects/manage-service-accounts). ## Create a service account 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**](/admin/organizations/organizations-overview#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'll need the client secret to retrieve an access token. > [!WARNING] > > You cannot view the client secret again after you close the dialog. 6. Click **Copy and Continue**. Once you've created a service account, [add it to a project](/admin/projects/manage-service-accounts#add-a-service-account-to-a-project) to give it access to the project's resources. ## Retrieve an access token To access the Admin API, you must authenticate with an access token. To get one, use the client secret you received when you [created the service account](#create-a-service-account). This example requests an access token for a service account from the `https://login.pinecone.io/oauth/token` endpoint: ```bash curl theme={null} curl "https://login.pinecone.io/oauth/token" \ -H "X-Pinecone-Api-Version: 2026-07" \ -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 includes 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 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 > Edit role**. 3. Select an [**Organization role**](/admin/organizations/organizations-overview#organization-roles) for the service account. 4. Click **Save**. ## Update service account name 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 > Rename**. 3. Enter a new **Name**. 4. Click **Save**. ## Rotate a service account's secret 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 secret**. 5. Copy and save the **Client secret** in a secure place for future use. > [!WARNING] > > You cannot view the client secret again after you close the dialog. 6. Click **Copy and Continue**. ## Delete a service account Deleting a service account removes it from all projects and disrupts any applications that use it to access Pinecone. 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**. # Organizations overview Source: https://docs.pinecone.io/admin/organizations/organizations-overview 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](/admin/projects/projects-overview) 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. > [!NOTE] > > An email address can be associated with multiple organizations, but each user can own at most 10 organizations. For information about managing organization members, see [Manage organization members](/admin/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 organization owners and billing admins. Organization owners and billing admins 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](/admin/security/security-overview#role-based-access-controls-rbac) (a user, service account, or API key) has within Pinecone. * **Organization owner** (`OrgOwner`): Full control over the organization, including billing, members, service accounts, security, and every project. Inherits [owner access](/admin/projects/projects-overview#project-roles) to all projects in the organization. * **Organization manager** (`OrgManager`): Can view organization details and create projects. Organization managers can't manage billing, members, service accounts, or organization settings. * **Organization member** (`OrgMember`): Can view organization details and access the projects they're added to. Organization members can't create projects or manage organization settings. To grant project access, add the member to one or more projects and assign a [project role](/admin/projects/projects-overview#project-roles). For steps, see [Manage project members](/admin/projects/manage-project-members). * **Billing admin** (`OrgBillingAdmin`): Can view organization details and manage billing, subscriptions, and usage. Billing admins can't manage members or organization settings, and they can't manage projects unless they're also [project owners](/admin/projects/projects-overview#project-roles). | 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. > [!NOTE] > > 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](/admin/security/configure-single-sign-on/okta). > [!NOTE] > > SSO is available on Standard and Enterprise plans. ## Service accounts > [!NOTE] > > This feature is available on the [Enterprise plan](https://www.pinecone.io/pricing/). [Service accounts](/admin/organizations/manage-service-accounts) enable programmatic access to Pinecone's Admin API, which you can use to create and manage projects and API keys. Use service accounts to automate infrastructure management and integrate Pinecone into your deployment workflows instead of working manually in the Pinecone console. Service accounts get their permissions from [organization roles](/admin/organizations/organizations-overview#organization-roles) and [project roles](/admin/projects/projects-overview#project-roles), and they give you a secure, auditable way to handle programmatic access. ## See also * [Manage organization members](/admin/organizations/manage-organization-members) * [Manage project members](/admin/projects/manage-project-members) # Create a project Source: https://docs.pinecone.io/admin/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). If you're an [organization owner or organization manager](/admin/organizations/organizations-overview#organization-roles), you can create a project in your organization. > [tab] Pinecone console > > 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 project name in **Give your project a name**. > > > [!NOTE] > > > > 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, Enterprise plan) Turn on **Enforce customer managed encryption (CMEK)**. For more information, see [Configure CMEK](/guides/production/configure-cmek). > > 6. Click **Create project**. > > To create an index from a sample movies dataset, go to **Database > Quickstart** and click **Load from dataset**. > > > [!NOTE] > > > > The number of projects per organization varies by plan. For details, see [Projects per organization](/reference/api/database-limits/object-limits). To create additional projects, [upgrade your plan](/admin/billing/upgrade-billing-plan). > [tab] Code > > > [!NOTE] > > > > To complete this action through the Admin API, you need an [access token](/admin/organizations/manage-service-accounts#retrieve-an-access-token). > > ```bash curl theme={null} > PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" > > curl "https://api.pinecone.io/admin/projects" \ > -H "X-Pinecone-Api-Version: 2026-07" \ > -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](/admin/projects/manage-project-members#add-members-to-a-project) * [Create an index](/guides/indexes/create-an-index) * [Create an assistant](/guides/assistant/create-assistant) # Manage API keys Source: https://docs.pinecone.io/admin/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](/admin/projects/projects-overview) has one or more API keys. 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. > [!WARNING] > > If you use custom API key permissions, make sure you [target your index by host](/guides/indexes/target-an-index#target-by-index-host-recommended) when performing data operations such as `upsert` and `query`. ## Create an API key > [tab] Pinecone console > > 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). > > 2. Select your project. > > 3. Go to **API keys**. > > 4. Click **+ 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](/admin/projects/projects-overview#project-roles). > > > [!NOTE] > > > > 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](/admin/billing/upgrade-billing-plan). > > 7. Click **Create key**. > > 8. Copy and save the generated API key in a secure place for future use. > > > [!WARNING] > > > > You cannot view the API key again after you close the dialog. > > 9. Click **Close**. > [tab] Code > > > [!NOTE] > > > > To complete this action through the Admin API, you need an [access token](/admin/organizations/manage-service-accounts#retrieve-an-access-token). > > ```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: 2026-07" \ > -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/api-keys/list-api-keys) for your project: > [tab] Pinecone console > > 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). > 2. Select your project. > 3. Go to the **API keys** tab. > > You'll see a list of all API keys for the project, including their names, creation dates, creators, partial values, and permissions. > [tab] Code > > > [!NOTE] > > > > To complete this action through the Admin API, you need an [access token](/admin/organizations/manage-service-accounts#retrieve-an-access-token). > > ```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: 2026-07" > ``` > > ```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/api-keys/get-api-key-details): > [tab] Pinecone console > > 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'll see the API key's name and permissions. > [tab] Code > > > [!NOTE] > > > > To complete this action through the Admin API, you need an [access token](/admin/organizations/manage-service-accounts#retrieve-an-access-token). > > ```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: 2026-07" > ``` > > ```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 > [!NOTE] > > Users on the Starter and Builder plans can't change API key permissions once they're set. Instead, [create a new API key](#create-an-api-key) or [upgrade to the Standard or Enterprise plan](/admin/billing/upgrade-billing-plan). If you're a [project owner](/admin/projects/projects-overview#project-roles), you can update an API key's permissions. To rename a key, use the API. > [tab] Pinecone console > > 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 permissions for the API key as needed. > > For information about the different API key permissions, see [Project roles](/admin/projects/projects-overview#project-roles). > > 6. Click **Update**. > [tab] Code > > > [!NOTE] > > > > To complete this action through the Admin API, you need an [access token](/admin/organizations/manage-service-accounts#retrieve-an-access-token). > > ```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: 2026-07" \ > -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're a [project owner](/admin/projects/projects-overview#project-roles), you can delete an API key. > [tab] Pinecone console > > 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 **Delete API key**. > > > [!WARNING] > > > > Deleting an API key is irreversible and immediately disables any applications using the API key. > [tab] Code > > > [!NOTE] > > > > To complete this action through the Admin API, you need an [access token](/admin/organizations/manage-service-accounts#retrieve-an-access-token). > > ```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: 2026-07" \ > -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/admin/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](/admin/organizations/organizations-overview#organization-roles) or [project owners](/admin/projects/projects-overview#project-roles) can manage members in a project. Each member is assigned one or more [project roles](/admin/projects/projects-overview#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](/admin/security/manage-rbac). > [!TIP] > > For information about managing members at the organization level, see [Manage organization members](/admin/organizations/manage-organization-members). ## Add members to a project > [!NOTE] > > Project owners can add existing organization members to a project and manage their project roles. Only [organization owners](/admin/organizations/organizations-overview#organization-roles) can invite people who aren't 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 [**Settings > Access**](https://app.pinecone.io/organizations/-/projects/-/access/members) and select the **Members** tab. 3. Enter the member's email address or name. 4. Select a [**Project role**](/admin/projects/projects-overview#project-roles) for the member. The role determines the member's permissions within Pinecone. 5. Click **Invite**. If the person is already a member of your organization, they get access to the project right away. Otherwise, Pinecone emails them an invite, and they join your organization as an organization member, with access to the project, when they accept it. ## 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 [**Settings > Access**](https://app.pinecone.io/organizations/-/projects/-/access/members) and select the **Members** tab. 3. In the row of the member you want to edit, click **ellipsis (...) menu > Edit role**. 4. Select a [**Project role**](/admin/projects/projects-overview#project-roles) for the member. 5. Click **Save**. ## 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 [**Settings > Access**](https://app.pinecone.io/organizations/-/projects/-/access/members) and select the **Members** tab. 3. In the row of the member you want to remove, click **ellipsis (...) menu > Remove from project**. 4. Click **Remove member**. > [!NOTE] > > To remove yourself from a project, in your user's row, click **ellipsis (...) menu > Leave project** and confirm. # Manage projects Source: https://docs.pinecone.io/admin/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. > [!NOTE] > > You must be an [organization owner](/admin/organizations/organizations-overview#organization-roles) or [project owner](/admin/projects/projects-overview#project-roles) to edit project details or delete a project. ## View project details This example retrieves the details of a project: > [!NOTE] > > To complete this action through the Admin API, you need an [access token](/admin/organizations/manage-service-accounts#retrieve-an-access-token). ```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: 2026-07" \ -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 ``` > [!TIP] > > You can also view project details in the [Pinecone console](https://app.pinecone.io/organizations/-/projects). ## Rename a project > [tab] 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. Enter a new **Name**. > > > [!NOTE] > > > > A project name can contain up to 512 characters. > > 4. Click **Save changes**. > [tab] Code > > > [!NOTE] > > > > To complete this action through the Admin API, you need an [access token](/admin/organizations/manage-service-accounts#retrieve-an-access-token). > > ```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: 2026-07" \ > -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(s)** and enter a tag key and value. Repeat for each tag you want to add. 4. Click **Save changes**. > [!TIP] > > You can also [add tags to indexes](/guides/indexes/manage-indexes#configure-index-tags). ## Delete a project To delete a project, you must first [delete all data](/guides/data/delete-data), [indexes](/guides/indexes/manage-indexes#delete-an-index), [collections](/guides/legacy/pod-based-indexes/back-up-a-pod-based-index#delete-a-collection), [backups](/guides/indexes/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. > [tab] Pinecone console > > 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**. > [tab] Code > > > [!NOTE] > > > > To complete this action through the Admin API, you need an [access token](/admin/organizations/manage-service-accounts#retrieve-an-access-token). > > ```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: 2026-07" \ > -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 project service accounts Source: https://docs.pinecone.io/admin/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. > [!NOTE] > > This feature is available on the [Enterprise plan](https://www.pinecone.io/pricing/). This page shows how [organization owners](/admin/organizations/organizations-overview#organization-roles) and [project owners](/admin/projects/projects-overview#project-roles) can add and manage service accounts at the project level. Service accounts enable programmatic access to Pinecone's Admin API, which you can use to create and manage projects and API keys. ## Add a service account to a project After a service account is [added to an organization](/admin/organizations/manage-service-accounts#create-a-service-account), you can add it to a project in the [Pinecone console](https://app.pinecone.io/organizations/-/projects): 1. Select your project. 2. Go to [**Settings > Access**](https://app.pinecone.io/organizations/-/projects/-/access/service-accounts) and select the **Service accounts** tab. 3. Select the service account to add. 4. Select a [**Project role**](/admin/projects/projects-overview#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 [**Settings > Access**](https://app.pinecone.io/organizations/-/projects/-/access/service-accounts) and select the **Service accounts** tab. 3. In the row of the service account you want to edit, click **ellipsis (...) menu > Edit role**. 4. Select a [**Project role**](/admin/projects/projects-overview#project-roles) for the service account. 5. Click **Save**. ## 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 [**Settings > Access**](https://app.pinecone.io/organizations/-/projects/-/access/service-accounts) and select the **Service accounts** tab. 3. In the row of the service account you want to remove, click **ellipsis (...) menu > Remove from project**. 4. Click **Remove service account**. # Projects overview Source: https://docs.pinecone.io/admin/projects/projects-overview 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](/admin/organizations/organizations-overview) and contains [indexes](/guides/indexes/index-data-overview), [assistants](/guides/assistant/overview), and users. Only a user who belongs to the project can access the indexes and assistants 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 lets you manage related resources across environments and access them with the same API key. ## Project roles If you're an [organization owner](/admin/organizations/organizations-overview#organization-roles) or project owner, you can manage who has access to a project. To grant a principal (a user, [service account](/admin/projects/manage-service-accounts), or [API key](/admin/projects/manage-api-keys)) access, assign 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 can't 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](/admin/projects/manage-service-accounts). | 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 owner, manager, and member roles have these project settings, resource, and data permissions: | 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) | ✓ | ✓ | | For pod-based indexes, the roles have these additional permissions: > [!WARNING] > > Pod-based indexes are legacy. Customers who signed up for a Standard or Enterprise plan on or after August 18, 2025 cannot create them. [Create a serverless index](/guides/indexes/create-an-index) instead. Serverless indexes use on-demand read capacity by default, or [dedicated read nodes](/guides/optimize/dedicated-read-nodes/overview) for sustained high query rates and workloads of millions of records or more. | Permission | Owner | Manager | Member | | :- | :-: | :-: | :-: | | View project pod limits | ✓ | ✓ | ✓ | | Update project pod limits | ✓ | | | | Update index size | ✓ | ✓ | | > [!NOTE] > > Pod-based indexes don't support role-based access control and always grant data plane read and write access to project members. ### Role permissions These tables list the operations each general, control plane, and data plane role covers: #### 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.
  • Standalone embedding and reranking: 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.
  • Standalone embedding and reranking: Permissions to generate embeddings and rerank documents.
| | None | No data plane permissions. | ## API keys Each Pinecone [project](/admin/projects/projects-overview) has one or more API keys. 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](/admin/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 * [Organizations overview](/admin/organizations/organizations-overview) * [Manage organization members](/admin/organizations/manage-organization-members) # Configure audit logs Source: https://docs.pinecone.io/admin/security/configure-audit-logs Enable Pinecone audit logging to an Amazon S3 or Google Cloud Storage bucket to track user, service account, and API actions for compliance and security review. Audit logs provide a detailed record of user, service account, and API actions that occur on the management and [control plane](/guides/get-started/architecture#control-plane) within Pinecone. Pinecone supports Amazon S3 and Google Cloud Storage (GCS) as destinations for audit logs. > [!NOTE] > > To enable and manage audit logs, you must be an [organization owner](/admin/organizations/organizations-overview#organization-roles). This feature is available only on [Enterprise plans](https://www.pinecone.io/pricing/) or with the [HIPAA compliance add-on](/guides/cost/understand-cost#hipaa-compliance-add-on). ## Enable audit logs 1. Give Pinecone write access to your bucket: * For Amazon S3, set up an [IAM policy and role](/guides/storage-integrations/integrate-with-amazon-s3). * For GCS, [create a service account and key](/guides/storage-integrations/integrate-with-google-cloud-storage#1-create-a-service-account-and-key), and [grant it access to the bucket](/guides/storage-integrations/integrate-with-google-cloud-storage#2-grant-access-to-the-bucket) with a role that can list, create, and delete objects. 2. Go to [**Settings > Audit logs**](https://app.pinecone.io/organizations/-/settings/logging) in the Pinecone console. 3. For **Destination**, select **Amazon S3** or **Google Cloud Storage**. 4. Enter the credentials for your bucket: * For Amazon S3, enter the **Role ARN** of the IAM role you created. * For GCS, paste the contents of your service account's JSON key file into **Service account key JSON**. 5. For **Bucket name**, enter the name of your bucket. > [!NOTE] > > To write audit logs to a specific subdirectory, enter `bucket-name/subdirectory-path` in the bucket name field, for example, `my-bucket/pinecone-logs`. For Amazon S3, make sure your [IAM policy is configured for subdirectory access](/guides/storage-integrations/integrate-with-amazon-s3#targeting-a-subdirectory-optional). For GCS, a role granted on the bucket already covers every subdirectory. 6. Click **Enable audit logs**. Once you enable audit logs, Pinecone starts writing logs to your bucket. Pinecone also writes a test file named `audit-log-access-test` to verify that it can write logs to the bucket, and then tries to delete it. The file stays in your bucket if Pinecone can't delete objects, as with the Amazon S3 policy. ## Make your audit-log bucket immutable (recommended) Audit logs are written to a bucket you control, so you can enforce write-once-read-many (WORM) immutability. Log files then can't be modified or deleted, even by your own administrators, for a retention period you define. We recommend this for compliance use cases. These steps cover Amazon S3 only. For Amazon S3, 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/storage-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 doesn't modify or delete previously written logs. > [!WARNING] > > Compliance mode is intentionally irreversible: until a retention period expires, objects can't be deleted and the period can't 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 your bucket every 30 minutes. Each log batch is saved to 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 are saved. For more information about the log schema and captured events, see [Audit logs](/admin/security/security-overview#audit-logs) in the security overview. ## Edit audit log integration details 1. Go to [**Settings > Audit logs**](https://app.pinecone.io/organizations/-/settings/logging). 2. Enter the new credentials or **Bucket name**. You can't change the destination of an existing integration. > [!NOTE] > > For GCS, Pinecone doesn't return your service account key after you save it, so paste the full key into **Service account key JSON** again whenever you update the integration. 3. Click **Update settings**. ## Disable audit logs Disabling audit logs pauses delivery to your bucket. Your integration settings are kept, and if you enable audit logs again, Pinecone delivers the logs that weren't written to your bucket before you disabled them. 1. Go to [**Settings > Audit logs**](https://app.pinecone.io/organizations/-/settings/logging). 2. Click the toggle next to **Audit logging is active**. 3. Click **Disable integration**. ## Remove audit log integration If you remove the audit log integration, logs that haven't been written to your bucket yet aren't delivered, even if you set up a new integration later. 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 SSO with Okta Source: https://docs.pinecone.io/admin/security/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. You can adapt these instructions for any provider with SAML 2.0 support. > [!NOTE] > > 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](/admin/organizations/organizations-overview#organization-roles). * Access to your organization's [Okta Admin console](https://login.okta.com/). ## 1. Start SSO setup in Pinecone In this step, you'll copy two values you need to configure 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 1. In [Okta](https://login.okta.com/), if you're not already on the Okta Admin console, click **Admin**. 2. Go 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 the 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` > [!NOTE] > > 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, go 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**. > [!WARNING] > > Download the certificate, don't copy it. The downloaded version contains necessary `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines. ## 4. Complete SSO setup in Pinecone Return to the browser tab or window you kept open in [Step 1](#1-start-sso-setup-in-pinecone). 1. In the **Setup SSO** dialog, 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). > [!WARNING] > > When pasting the certificate, include the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines. 2. Choose whether 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. > [!NOTE] > > The **Default role** doesn't apply if you enable [SAML role management](/admin/security/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. > [!WARNING] > > When users first log in through 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 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 through 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 through SSO while the default was **Owner**. If they did, adjust their roles. > * **Multiple owners**: Keep at least one owner signed in with email while others log in through SSO. That owner can restore roles as needed, then log in through SSO last. > > If all owners lose access, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Okta is now ready for single sign-on. To add users and groups, see the [Okta docs](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-main.htm). ## Manage roles automatically You can also 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](/admin/security/configure-single-sign-on/okta-role-management). # Manage roles with Okta Source: https://docs.pinecone.io/admin/security/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](/admin/security/configure-single-sign-on/okta) and shows how to set up SAML role management with Okta. You can adapt these instructions for any provider with SAML 2.0 support. > [!NOTE] > > SAML role management is available on the Enterprise plan and builds on SAML SSO. Before you begin, [configure SSO with Okta](/admin/security/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** isn't 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. > [!NOTE] > > 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. The assignments remain but grant no access on their own. To clear them, or to have Pinecone remove members automatically, use [SCIM provisioning](/admin/security/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. > [!WARNING] > > 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](/admin/projects/projects-overview#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](/admin/organizations/organizations-overview#organization-roles) grants, see [Organizations overview](/admin/organizations/organizations-overview#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](/admin/projects/projects-overview#project-roles) grants, see [Projects overview](/admin/projects/projects-overview#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. > [!NOTE] > > 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]`. > [!NOTE] > > 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 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). > [!WARNING] > > 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. A malformed expression returns no roles rather than an error. ## 3. Enable SAML role management in Pinecone > [!NOTE] > > You must be an [organization owner](/admin/organizations/organizations-overview#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 doesn't, 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/admin/security/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](/admin/security/configure-single-sign-on/okta) and shows how to set up SCIM provisioning with Okta. You can adapt these instructions for any provider with SCIM 2.0 support. > [!NOTE] > > SCIM provisioning is available on the Enterprise plan and builds on SAML SSO. Before you begin, [configure SSO with Okta](/admin/security/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. For the other attributes Pinecone reads, see [Supported attributes](#supported-attributes). * 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. > [!NOTE] > > Provisioning changes in Okta are typically reflected in Pinecone within a few minutes, but can take up to 30 minutes to fully propagate. > [!NOTE] > > SCIM provisioning assigns roles from user attributes only. SCIM group push isn't supported. This is similar to [SAML role management](/admin/security/configure-single-sign-on/okta-role-management), except roles are provisioned continuously rather than at each login, and member deprovisioning is handled automatically. > [!WARNING] > > Before you enable SCIM, provision at least one current [organization owner](/admin/organizations/organizations-overview#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. ## Supported attributes Pinecone reads the following SCIM user attributes and ignores all others, including `emails`, `phoneNumbers`, `addresses`, `photos`, `title`, and enterprise extension attributes such as `department` and `manager`. A member needs both required attributes to get access. Okta can't provision a member without `userName`, and a member whose `roles` has no organization role has no access to the organization. | SCIM attribute | Required | How Pinecone uses it | | :- | :- | :- | | `userName` | Yes | The member's email address, which must match the one they use to sign in through SAML SSO. See [Step 3](#3-connect-okta-to-the-scim-endpoint). | | `roles` | Yes | The member's organization and project roles. See [Role attribute values](#role-attribute-values). | | `active` | No | Whether the member is active. Setting it to `false` removes the member from the organization. If Okta doesn't send it, Pinecone treats the member as active. | | `displayName` | No | The member's name, shown in the Pinecone console. | | `name.givenName` | No | The member's first name. Stored on the member's profile, but not shown in the console. | | `name.familyName` | No | The member's last name. Stored on the member's profile, but not shown in the console. | The console shows a member's `displayName`, or their email address if Okta doesn't send one. To show members' names in the console, keep the `displayName` mapping. ## 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](/admin/projects/projects-overview#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](/admin/organizations/organizations-overview#organization-roles) grants, see [Organizations overview](/admin/organizations/organizations-overview#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](/admin/projects/projects-overview#project-roles) grants, see [Projects overview](/admin/projects/projects-overview#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 > [!NOTE] > > You must be an [organization owner](/admin/organizations/organizations-overview#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 doesn't, 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). > [!WARNING] > > The bearer token is shown only once. Copy it before closing the dialog. You can have at most two active tokens per organization. You can 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**. 7. Still under **Provisioning > To App**, scroll to **Pinecone Attribute Mappings** and check the source for `userName`. If it's set to `user.login` or an Active Directory attribute, change it to `user.email` and click **Save**. > [!WARNING] > > The SCIM `userName` must be the same email address your members sign in with through SAML SSO. If your members are sourced from Active Directory or LDAP, `user.login` is often a local domain login such as `user@example.local` rather than an email address. When the two values differ, Pinecone treats the provisioned member and the member who signs in as two different people. The result is duplicate accounts, and sign-in fails with a `jit_disabled` error. Fix the mapping before you enable SCIM in [Step 6](#6-enable-scim-in-pinecone). > [!NOTE] > > If the **Provisioning** tab or **Configure API Integration** button doesn't appear, SCIM provisioning isn't enabled on the app. > > If **Test API Credentials** fails, re-copy the SCIM endpoint and bearer token from Pinecone, and confirm the token hasn't expired or been revoked. ## 4. Send role values to Pinecone Okta doesn't 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=='